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INTRODUCTION 


* 

is a reference guide to the 135 system 
features in the APL*PLUS/PC System and is directed toward 
advanced users. If you are not an experienced APL user, you 
Should read a good introductory text, such as APL Ig Easy! 
(STSC, 1983) or APL: An Interactive Approach (Wiley, 1983). 
For more information of the file system functions, read the 
APL*PLUS/PC_Pile ers's Guide. The Formatting 
User's Guide explains the system function DFM? in detail. 


Organization of the Manual 
Chapter 1 is an overview of the system functions, 


system variables, and system constants in the APL*PLUS/PC 
System. 


Chapter 2 organizes the system functions, system 
variables, and system constants into related groups. 


Chapter 3 explains each feature in detail. Syntax, 
arguments, and results are given for system functions; the 
Gomain, reference and default values, and value-dependent 
primitive functions are given for system variables. 
Descriptions and examples are included for each feature. 


Syntax Conventions 


All items in APL (italic) font represent information to 
be entered exactly as shown. Although DOS commands can be 
entered using either upper- or lowercase characters, DOS 
commands in this manual are shown in uppercase italic 
letters. Lowercase roman font with a leading capital letter 
is used to indicate keys that appear on the keyboard this 
way: for example, Alt, Ctrl, Esc, and Break. Items in 
lowercase, underlined roman font are mnenonic 
representations for information to be supplied by the user. 
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System Functions 


NOTE 


The system function [POKE is used to change many 
optional features of the APL«PLUS/PC System. If 
you want to use a feature that is described vith a 
phrase such as "changed with a [IPOKE" or "changed 
with [IPOKE nn", look up this feature in the table 
of -POKE options in the description of the LPOKE 


System function in this manual. Note that 
incorrect use of [POKE vill cause unpredictable 
results and usually crash the system. You must 
observe the cautions explained in the description 
of SPOKE. 


We're eager to hear your comments on this manual and on 
the APL*PLUS/PC System. We've included a Feedback Form and 
postage-paid mailer at the back of this manual for your 
convenience. If the form is missing, please send your 
comments to: 


STSC, Inc. 

Marketing Communications 
2115 East Jefferson Street 
Rockville. Maryland 20852 
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CHAPTER 1 


OVERVIEW 


System functions, system variables, and system 
constants are features that are alvays available in any 
workspace. In APL symbol form, they are easily recognized 
by the [] with which their names begin; for example, OLOAD or 
ÜRELP. 


In keyword form, these names display in lowercase. The 
keyword marker that replaces the D can be suppressed. The 
default keyword marker, #, can be changed with a JPOKE. 


Names that begin with Z (in symbol form) or a keyword 
marker (in keyword form) are reserved for use by the system 
and cannot be used for user-defined objects. 


The system features in the APL*PLUS/PC System are 
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Many of these system features directly cause the desired 
processing to occur. Some, such as C7, O70, and ORL. 
affect system behavior indirectly. Additional ways of 
controlling system behavior indirectly are described under 
"DPOKE -- Poke into CPU Memory", and also in "DOS and the 
APL*PLUS/PC System" in the APL*PLUS/PC Programmer's Manual 
(STSC, 1983). 


1.1 System Functions 

System functions share many of the properties of APL 
primitive functions: they are always available for use in 
the workspace; they can be incorporated in user-defined 
functions; some have both monadic and dyadic definitions 
(called "ambivalent" functions); and most return an explicit 
result that can be used in subsequent operations. 


System functions are dyadic, monadic, or niladic. 
Typically, they: 


* provide information about the session 
* provide information about the active vorkspace 


* provide information about objects in the active 
workspace 


* retrieve other objects or workspaces from the disk 
libraries 


* assist in debugging programs 
* communicate with another device 
» manipulate the screen or assist in making graphs 


* indicate the status of the relevant enviromment 
(that is, have an explicit result) 


e produce an effect on the environment. 


1.2 System Variables 


System variables are a special class of APL variables 
that are used to manage the interaction between the APL 
processor and the active workspace, as well as the 
interaction between the APL processor and the screen and 
keyboard. 
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System variables provide a means of holding certain 
special information that you, your programs, or the system 
Can always find in any workspace. To the user, system 
variables behave as ordinary variables with some special 
properties; to the system, they are a set of parameters 
controlling the interface vith the user. 


System variables are always available. They can be 
referenced or they can be assigned values at vill, and they 
can be localized in functions. However, system variables 
cannot be erased or copied. 


There are restrictions on the domain of assignment for 
System variables. When an invalid assignment is attempted, 
an error report is displayed and the value of the system 
variable remains unchanged. 


System variables can be localized in user-defined 
functions, They are similar tb other localized variables 
except in the following respects: 


° Names of system variables cannot be used as names of 
labels, nor as names of the arguments, the result, 
or the function name in a function header. 


* When a session-related system variable is no longer 
shadowed (upon returning from function execution or 
loading a workspace), it takes on the global value 
associated with the session. 


* When execution depends on a system variable that is 
localized but has no assigned value, the value in 
use at the time the function was called is used. 
This value remains unless re-assigned. This is 
sometimes called "pass-through localization", The 
sole exception to pass-through localization of 
system variables in the APL«PLUS/PC System is DSA, 
for which a default local value of 'FXIT' is 
assumed. 


System variables on the APL*PLUS System are classified 
as workspace-related or session-related. 
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Workspace-related system variables are stored vith the 
workspace and are possibly altered whenever a workspace is 
loaded. various primitive functions depend upon the value 
of one or more of these variables. Workspace-related system 


variables are summarized in the table belov. o 
5 Acceptable Default 
Name Meaning values __ Valve __ 
DALX Attention Latent Character "Üpu* 
Expression vector or 
singleton 
Der Comparison Tolerance 0s CCT« 2* 13 246 
UELX Error Latent Character “OD? 
Expression vector or 
singleton 
HELP filenames 22-column 1 220 18t'SYSBELP' 
to be used character 
matrix or 
vector 
ÜRTOPIC HELP default Character ae 
topic vector or o 
singleton 
m Index Origin 0 or 1 H 
Latent Expression Character vs 
vector or 
singleton 
DPP Printing Precision An integer 10 
from 1 tọ 17 
TRL Random Link 1 to 725231 16807 
TSA Stop Action tt, ‘CLEAR, i$ 
EXIT', or ‘OFF? 
DSEG Memory Segment 8 or an integer e 
from 732768 to 
32787 


The default values of workspace-related system 

variables are established in a clear workspace, and their 

current values are those values (possibly localized) 

associated with the active workspace. As with user-defined o 
variables that are localized, when a workspace-related 

system variable is no longer shadowed (upon return from 

function execution) it takes on the global value associated 

with the workspace. 
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Session-related system variables are not saved with any 
workspace, except where they are localized in pendent or 
executing functions. No primitive functions depend upon the 
values of these variables. Session-related system variables 
are summarized in the table below. 


Acceptable Default 
Name Meaning Valves ___ Value... 
ÜCURSOR Cursor Position Integers from 00 
9 through 
14 2*0WINDOV 
OKEYW Keyword Setting 0 or 1 o 
Dew Printing Width Integers from BO or 40 
30 through 255 
DWINDOW Screen Window Integers from 0 0 25 80 
0 0 25 80 up or 
to 24 79 1 1 0 0 25 40 


The default values of session-related system variables are 
established at the start of each APL session. ‘PW and [WINDOW 
default widths depend upon the number of columns on the monitor in 
use at entry to the system. These values remain in effect until 
new values are assigned (possibly in the latent expression of your 
initial workspace). Loading a workspace does not affect the 
global values of these variables for the session. The value of a 
localized session variable temporarily supersedes the global 
value. When a session-related system variable is no longer 
shadowed (upon return from function execution). the variable takes 
on the global value associated with the session. 


3.3 System Constants 


System constants are values that are available in any 
workspace and that do not change within a given APL system. 
In the APL*PLUS/PC System, they are niladic system functions 
and include Day, DFAVAIL, [JSYSID. DTCBEL, QTCBS. DTCDEL, 
Orcesc, ÜTCFF. ÜTCLF, ÜTCNL, DTCNUL. and DUL. 
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CHAPTER 2 


RELATED GROUPS 


Certain system functions, system variables, and system 
constants form naturally related groups and are best 
understood together: 


APL Component Files:  -FAPPEND, LFAVAIL, (FCREATE, 
ÜFDROP, CFDUP, ÜIFERASE. JFHOLD, “FLIB, [FNAMES, 
DFNUMS, GFRDAC, CFRDCI, JFREAD, -FRENAME, “FREPLACE, 
ÜFRESIZE, QFSIZE, FSTAC, QFSTIE. SETIE, OPUNTIE 


Character Constants: "AV, OTC, "TCBEL, -TCBS, 
CTCDEL, CTCESC, LTCFF, 'TCLF, ÜTCNL, ÜTCNUL 


Debugging Tools: ZCRL, DEDIT, JIDLIST, JIDLOC, ILC, 


DSTOP, UTRACE, WR 


Detached Input and Output (allowing you to shift 
output from the screen to a file or both, or replace 
keyboard input by a prerecorded file or record such 
a file by keeping only the keyboard input from part 
of your APL session for future use): ([caP, LIN, 
Qyrosrare, Jour 


Disk Related: (cmp, DFLIB, ÜLIB, (WSLIB (See also 
APL and native file functions, and workspace related 
functions.) 


DOS Related: CCMD 


Exception Handling: ALY, JDM, DELX, DERROR, OSA 


Execution: ODL. DIDLOC, OLC, ZSA, OSI, ÜSINL 


Tere, LICRLPC. Goer, [DEFL, DEDIT, JERASE, JEX, Z 
LLOCK, WR 


General Information: ( r CURSOR, JFRDCI, 
ZSYMB, -SYSID,. . CWSSIZE, 
WSTS 


Graphics Related: [DGCIRCLE, []GINIT, DGLINE, OGMASK, 
IGPAINT, ÜGPRINT. ÜGSBHADE. DGSTATUS, DGTYPE, DGVIEV, 
DEWINDOW, .GWRITE, D6200M 
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* HELP Related: [FELP, [ENAMES, [TOPIC 


* Input Related: [JARBIN, DEDIT, OFI, [INBUF, [INKEY, 
JKEYW, DVI, WIN, DWKEY 


o Keyboard Related:  /JARBIN, [INBUF, SINKEY, DINT, 
QKEYW, (PFKEY, [POKE 


* Latent Expressions: [4LX, DELY, DLX 
* Machine Language Related: ICALL, CINT, ÜSTPTR 
e Memory Related: (PEEK, DPOKE, SEG 
* Native Files: (LIB, DLIBS, (NAPPEND, INCREATE, 


ÜNERASE, DNNAMES, ÜINNUMS, UNREAD, DNREPLACE, 
ÜNRESIZE, ÜNSIZE, ONTIE, DNUNTIE 


* Object Related: JDR, [ERASE, DEX, CIDLIST, DIDLOC, 
ONC, ONL, USIZE, USYMB 


e Output Related: [ARBIN, []ARBOUT. JFMT. DOUT 


* Screen Related: [JARBIN, [jARBOUT, “CRT, “CURSOR, 
Qe¢vrew, (WGET, WINDOW, .WPUT (See also the 
graphics-related functions.) 

e Session Related: [ICURSOR, OXEYW¥, CPW, [WINDOM 

* Sound Related: [ISOVND, UTCBEL 


* State Indicator Related: LIDLIST, DIDLOC, Owe, ONL, 
Ost, OSINL 


e Workspace and Object Manipulation: (copy, DLIB. 
ÜLI8S, DLOAD, CPCOPY. TQLO4D, WSID, (WSLIB, 
DWSOWNER. CWSSIZE, UWSTS. CXLOAD 


* Workspace Related:  .ALX. DICT. JELX, “70, OPP, ORL, 
Osa, CSEG, QSYMB 


* Other: (DL, DSS 
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CHAPTER 3 
DETAILS OF SYSTEM FUNCTIONS, VARIABLES, AND CONSTANTS 


On the following pages, all of the system functions, 
variables, and constants are listed in alphabetical order 
and are examined in detail. Users of terminal mode and 
Other APL systems should note that these details may not all 
correspond fully to those of similarly named objects on 
other systems. For your convenience in rapidly locating 
entries in the alphabetical listing, the names appear at the 
top of the outside margin. 
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ing Information DAI 


The niladic system function GAI returns current 
accounting information. DAIJ, as described here, is specific 
to the APL«PLUS/PC System; it may be different or absent in 
other APL*PLUS Systems. 


Syntax 
result + DAI 
result - the explicit result 
Result 


The explicit result of [J47 is a four-element numeric 
vector containing the following information: 


[1] The user's account number (identification code). 


[2] The cumulative number of seconds since the start 
of this APL session. 


[3] The cumulative number of characters entered from 
the keyboard during this APL session. 


[4] The cumulative number of characters output during 
this APL session. 


DAI relies on the system clock maintained by DOS for 
its time measurement. DOS reports time rounded to the 
nearest centisecond, but the accuracy is limited by the 
frequency with which the clock changes value. Many personal 
Computer systems have clocks that cannot measure time 
intervals shorter than 1/20 or 1/60 of a second because the 
Clock does not "tick" (change value) more frequently. The 
Clock in the IBM Personal Computer, and in others similar to 
it, ticks 18.2 times per second. Refer to your computer 
manufacturer's manual for a description of the precision of 
your system clock. 


CAUTION: User-defined functions should not depend on 
the result of JAT being a four-element vector, since more 
elements may be appended to the result in future releases of 
this system. 


ample 
60 60 60TDA4I(2] (assuming DI0+1) 
0 6 24.75 (hours, minutes, and seconds 
elapsed since starting APL session) 
Error Report 
WS FULL The explicit result requires more 


workspace storage than is available. 
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CALX 


Attention_Latent Expression Darx 


The workspace-related system variable [ALX holds a 
representation of the APL expression to be executed in the 
event of an attention exception. 


Domain 


The domain for assignment to (i4LX is a character 
Singleton or vector. 


Value vhen Referenced 


When DALX is referenced, its value is a character 
vector. 
Defaul a Clear Workspace 


In a clear workspace, the default value for JALY is 
IDN’. 


Dependent P: 


No primitive functions depend upon the value of (ALX. 


Whenever an attention exception occurs during the 
execution of an APL statement or function, the statement 
*DALX is executed. The most local value of ITALY is 
referenced. 


The circumstances defining an attention exception are 
controlled by tvo factors: the type of interrupt signal 
entered by the user; and the APL statement or function line 
being executed when the signal is generated. A weak 
interrupt, such as pressing BREAK once, is interpreted by 
the system as a request to stop execution as soon as it has 
finished executing the current function line. A strong 
interrupt, which can be generated by pressing BREAK twice in 
rapid succession, is interpreted by the system as a request 
to stop execution immediately and does not signal an 
attention exception. Note that pressing BREAK twice does 
not necessarily generate a stong interrupt, since the system 
may reach a stopping point acceptable for a veak interrupt 
before receiving the second signal. 


When BREAK is pressed once, the system finishes 
executing the current line, suspends the function, and 
executes JALX, unless one of the following conditions occurs 
between the BREAK and the line end: 


e The user presses BREAK again. In this event, a 
strong interrupt is generated, producing a 
suspension of execution and the display of the 
INTERRUPT message. 
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* An error exception is signaled. In this event, the 
error is handled first and, if execution resumes, 
the attention exception is signaled when the next 
function line is reached. 


* The function completes execution. In this event, 
the BREAK is ignored. 


* The function stops to request I or [| input. In this 
event, the BREAK is ignored. 


To summarize, the action specified by [LY is taken 
whenever a function suspends between lines as a result of a 
user-generated veak interrupt. An attention exception is 
not recognized until after completion of the first 
non-comment line of a function. 


Examples 


In the first example, [4LY is used to protect a 
critical function from suspension on a veak interrupt by 
automatically restarting the function. Since strong 
interrupts cannot be handled in this way, persons who use 
the application must use BREAK sparingly, Note that DLC in 
the APL«PLUS/PC System has no element corresponding to the e 
that would show in the SI during the execution of the 
statement *TALy. 


9 SAMPLE;ZALI V SAMPLE2;DALX 
[13 Qabxe*scree [1]  DALXe'CERROR ‘ATTN * 


v v 


The function SAMPLE2 uses [JALX to pass a special error 
exception to the function that called it. The calling 
function can then determine that the error results from an 
attention exception and take appropriate action. 


During Execution Any APL execution error can occur during 
the execution of DALY. 


DOMAIN ERROR The value being assigned is not 
character-valued or contains unmatched 
quotes. 

LIMIT ERROR The argument contains the character 


representation of a number whose absolute 
value is greater than 
1.797693134862316E308. 


RANK ERROR The value being assigned to [ALI is not a 
singleton or a vector. 
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JARBIN -- Arbitrary Input DARBIN 


The dyadic system function CARBIN permits transmission 
and reception of data to and from RS-232 ports, the printer, 
the screen, and the keyboard.  ( ARBIN can be used to 
communicate with a remote computer using the RS-232 port.) 
ÜMRBIN, as described here, is specific to the APL*PLUS/PC 
System; it may be different or absent in other APL*PLUS 
Systems. 


1f [MRBIN is used with the RS-232 port (COM1), the baud 
rate (transmission speed) must be set using the DOS MODE 


command. (For more information, see "DOS and the 
APL«PLUS/PC System" in the Programmer's Manual.) 


Syntax 
resvlt + parameterlist j4RBIN prompt 


- the explicit result 
list - a singleton or a vector of integers 
- any APL array 


Argument - Parameterlist 


The left argument is a vector (or singleton) of 
integers describing how the communication is to be carried 
out. If the left argument is a singleton, it specifies the 
outport and awaits no input, but immediately resumes local 
processing. If input is expected, or if you are specifying 
values other than default values, the left argument contains 
the following elements in this order: 


(1) gutport - destination to send data (for example, 
COM1, LPT1) 


(2) inport - source from which data is to be received 
(for example, COM1) 


(3) translation - translation table to be used (for 
example, ASCII, APL) 


(4) protocol - transmission protocol to be used (for 
example, XON/XOFF) 


(5) wait - number of seconds to wait for data 
(6) charlimit - maximum number of characters of data 
(7) terminators ~ list of termination codes. 
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The elements are used starting from the left; if fewer than 
six values are given, the remaining parameters assume the 
default values listed for them in their descriptions below. 


(1) & (2) gutport and inport - the destination or source 
for data, where: 


0 means no port; for transmission without expecting 
reception, inport should be set to 0; for reception 
without transmission (for example, flushing the COMI 
buffer), set outport to 0 


1 means the first serial (RS-232) port (known to DOS 
as COM1); can be used for concurrent 1/0 


2 means the second serial port (known to DOS as COM2) 


3 means the first parallel port (known to DOS as LPT1) 
-- for use with outport only 


4 means the second parallel port -- for use with 
outport only 


5 means the third parallel port -- for use vith 
outport only 


6 means screen characters (starting at cursor); can 
send any elements of [V or any keystrokes as 
integers from 0 through 511 inclusive; all 
non-visible characters in DAV, such as DTCHL, are 
converted to a visible character 


7 means insert screen attributes (starting at cursor) 


8 means insert screen characters (starting at cursor) 
-- for use with outport only; can send any elements 
of [47 or any keystrokes as integers from 0 through 
511 inclusive 


9 means screen actions like cursor movement, 
scrolling, erasures, deletions, and wrap markers, 
expressed as (DAV:DINKEY)-DIO for the key, such as 
PgUp (starting at the current cursor position) -- 
for use with outport only 


10 means user-supplied driver routine (interfaced via 
INT 90hex) 


Copyright 1983 STSC, Inc. 3-7 System Functions 


11 means the keyboard; when used with translation “1, 
this inport returns numeric values in the range 0 
through 511, where values over 255 represent 
Special keys (such as the cursor keys) as 
(DAViCINKEY)*256-D10.  LPFKEY and user programs can, 
therefore, distinguish them from character keys. 
When used with a special []POKE, displays partial 
results on screen, keystroke-by-keystroke as typed. 
except terminator -- for use with inport only 


12 means DOS "standard input", possibly redirected via 
DOS -- for use with inport only 


13 means DOS "standard output", possibly redirected via 
DOS -- for use with outport only 


14 means DOS "standard auxiliary", usually COM1 


15 means DOS "standard printer" -- for use with outport 
only. 


Note that depending on the outport or inport selected, 

some other elements of the left argument can become 

meaningless. Meaningless elements are ignored. 

The default inport value is 0. 

(3) translation - the translation tables (if any) where: 
o 7i means raw untranslated numeric codes 

0 means the APL-ASCI: typewriter-pairing overlay 

1 means the APL-ASCII bit-pairing overlay 

2 means untranslated ASCII 

3 means EPSON dot graphics (for representing APL's DAV 
characters on EPSON MX, RX, and FX series printers 
and the IBM graphics printer). 

The default translations are 0 for the serial ports (1 

and 2), 2 (but changeable as shown under (JPOKE) for 


the parallel ports (3, à, and 5) and port 10, and 2 
(mot changed by the DPOKE) for all other ports. 
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(4) protocol - the transmission protocol (if any) to be 
used with the serial ports, where: 


9 means none, no checks made before sending 


1 means XON/XOFF (DCi/DC3 or Ctrl Q/Ctrl S) 


means RTS/CTS 


e 


means both 1 and 2. 
The default protocol value is 3. 


(5) wait - the maximum number of elapsed seconds to 
wait for data. A value of 0 selects no 
wait. A negative value selects no timeout 
(a vait for any other terminating 
character). 


The default wait value is . 

(6) charlimit - the maximum number of characters of input 
desired, up to a maximum of 32,767. A 
value of 0 indicates that no response is 
expected at this time. Execution of 
LARBIN terminates when this number of 
Characters has been received. 


The default character limit value, if none is 
specified, is 0. To receive one or more characters, a 
minimum value of 2 is needed, since the last character 
is always the terminator, 


(7) terminators - a list (possibly empty? of termination 
codes. Execution of [ARBIN terminates 
when one of these codes is received. 
(For character to numeric equivalents, 
see “Transmission Code Tables" in the 
Programmer's _Manyal. ) 


The default terminator list, if none is specified, is 
empty. 
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Argument - Prompt 


The right argument (prompt) is an array of either 
Characters or integers to be transmitted before awaiting 
input. The right argument can be of any rank; it is raveled 
before being transmitted. It can also be of any length; it 
is not limited by the value of JPW. 


Result 


When input is requested, the result of [ARBIN is a 
vector, character or numeric, as specified in the 
translation. 


If an inport or charlimit of 0 is specified, or if the 
left argument has only one element (indicating only output 
is performed), the explicit result is an empty character 
matrix. This is returned immediately and local processing 
continues. 


The table below shows what happens in the event of 
DA4RBIN termination: 


Cause of Termination Last Element in Result 


A termination code was The termination code. 


received. 


No data was received or 
Successfully sent by the 


D47[1294DI0] in a character 
result or 129 in a numeric 


wait limit. 


The Break key was pressed 
once before or during the 
execution of [ARBIN. 


The charlimit has been 
satisfied. 


result. 
The character [MVt131«[01 
or the number 131. 


The character DAv[130+070] 
or the number 130. 


Effect 


The effect of DARBIN is to transmit the data to the 
specified port and wait or not wait (as dictated in the left 
argument) for a response before returning its explicit 
result. If a wait is specified, the explicit result is the 
response received up to termination, If no vait is 
specified (by a 0 value for wait, charlimit, or inport), an 
empty explicit result is returned inmediately. allowing 
local processing to resume at once. 


Be careful to ensure that the buffer does not overflow 
during concurrent 1/0. This occurs if more characters are 
received than the buffer can hold and nothing is emptied out 
(read from the buffer). 
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1f the prompt sent to the remote computer, or the 
desired result data received from the remote computer, 
contains characters that cannot be entered in character 
constants from the keyboard (such as DTCNL or CICLF), 
reception of data may terminate. It may be necessary to 
replace these characters with surrogates before 
transmission, and to remove the surrogates after 
transnission. 


Sending a numeric ^1 to à serial port signals a modem 
BREAK (continuous mark). 


Examples 
1. Send data directly to the printer: 
3 0 3 [JARBIN 'ABCDE', [TCNL 


The outport of 3 specifies LPT1, the inport of 0 says no 
response is expected. A translation of 3 means EPSON 
dot graphics for APL characters. 


2. Send a command to a Hayes Smartmodem(TM) connected to 
COMi to dial the phone: 


1 0 2 JARBIN 'ATDT5551212', LTCNL 


The inport is 1 for the first serial port. The outport 
is 0, specifying that no response is expected, and the 
translation is to to 2 for untranslated ASCII. The text 
"AT" signals the Hayes Smartmodem that a command 
follows. 


3. Read one key (if any) from the keyboard buffer. 
“140 112 0 0 2 CÁARBIN '' 


The outport of 0 specifies that no data is sent. An 
inport of 11 means to get data from the keyboard buffer. 
The translation is set to 2, for untranslated ASCII, the 
protocol and wait are set to 0. The charlimit is 2, for 
one character from the keyboard buffer and the 
termination character. This termination character is 
discarded with the 71+. 


^. Send the command )VARS to APL on a host computer and get 
the result back on your PC: 


1100 60 3000 7 JARBIN ')VARS', CTCNL 


COM1 is specified for both ports, no translation or 
Protocol is used. The wait is set to a maximum of 60 
seconds ànd the charlimit to no more than 3000 
characters. The termination character to be looked for 
is the bell, [4v(74210]. 
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5. Scroll screen memory up 10 lines: 


9 GARBIN 100136 


The gutport of 9 selects screen actions. When the PgUp 
e key is pressed, 136 is the result of (CAViDINKEY)-DIÓ. 
Error Reports 


DOMAIN ERROR 


© RANK ERROR 


WS FULL 


The left argument contains values that are 
not integer or are over 32,767, or 
contains negative numbers in positions 
other than translation or wait; the left 
argument specifies values for inport or 
outport other than those defined and 
installed; the left argument specifies a 
translation or protocol value other than 
those defined; or a terminator value of 
over 255 is used. 


Or, integers outside the range “1 to 255 
occur in the right argument. 


Or. with a translation value of 0 or 1, 
the received data has attempted to move 
the cursor left beyond the start of the 
transmitted text. 


The left argument is not a vector or 
singleton. 


The explicit result requires more 
workspace storage than is available. 
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ARBOUT -- Arbitrary Output to Screen DA4RBOUT 


The monadic system function G4RBOUT sends arbitrary 
character data to the screen of the personal computer, 
representing (interpreting) the numeric codes given in its 
argument as the corresponding elements of (MY.  .ARBOUT, as 
described here, is specific to the APL*PLUS/PC System; it 
may be different or absent in other APL«PLUS Systems. 


Syntax 
D4RBOUT codes 
£odes - the set of codes to be displayed 


Argument 


The argument is an integer array with values from 0 to 
255 inclusive. The argument can be of any rank; it is 
raveled before being displayed. The argument can also be of 
any length; it is not limited by the value of 


Result 


The function [ARBOUT does not return an explicit 
result. 


Effects 


DARBOUT displays each element of its argument on the 
screen as the corresponding element of [MV. 


The use of DARBOUT with any value discards any [+ 
prompt from the explicit result of a subsequent [| input 
request (see "Input on Same Line as Character Prompt" in the 
Programmer's Manual 


Example 
Te ' PROMPT: t 
DARBOUT 10 o ANSWER] (Assures that ANSWER will be 
PROMPT: MY REPLI... prompt-free regardless of the 
ANSWER value of [PEEK 96). 
MY REPLY 
Error Report 
DOMAIN ERROR The argument is not composed of integers 


in the range 0 through 255. 
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"n 


y Oav 


The system constant [MY returns a vector of all 
possible character values in the APL*PLUS/PC System. The 
detailed contents are shown in "The APL*PLUS/PC System's 
Gav" in the Programmer's Manual. 


Syntax 
result + Gay 
result - the explicit result 
Result 


The explicit result of [AV is a 256-element vector of 
all possible character values in the APL*PLUS/PC System. 
Users should avoid relying heavily on the order in which the 
APL*PLUS/PC System character set is mapped onto the elements 
in [MY. since this may change in a subsequent release of the 
System. All possible characters are represented somewhere 
in DAV, however -- even those not available directly from 
the keyboard. The explicit result can be indexed and the 
results stored in variables. Throughout this manual, all 
subscripts into [MV are shown in index origin 1. 


Note that the entire result of [AV cannot be displayed 
on the screen at the same time, since one of its elements 
clears the screen. 


The graphics characters for drawing lines and shading 
are found in D4Y[176*148). 


Examples 


NEW-ALLCAPSIOAV vOLD] (Translates character values. 
Makes NEM a revised version 
of OLD with characters 
remapped. For all I«1256, 
all occurrences of QAVLI) in 
OLD become ALLCAPSLI] in the 
corresponding position in 
NEW.) 


Error Report 


WS FULL The explicit result requires more 
workspace storage than is available. 
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ALL -- Call Machi nguage Routine Dcarr 


The system function [CALL causes the execution of the 
contents of an APL data object (named or temporary) as a 
machine language routine vith a possible subsequent return 
(for far procedures in Assembly language) to the APL session 
in progress. [CALL, as described here, is specific to the 
APL*PLUS/PC System; it may be different or absent in other 
APL*PLUS Systems. 


Syntax 
result + 
result + 
result - the explicit result 
registers - a singleton or vector of 0 to ? integers 


routine  - any non-empty APL array containing the 
machine language routine to be executed 


The optional left argument specifies the values of the 
CPU registers to be used upon entry into the routine 
specified in the right argument. Up to seven integers can 
be given and vill be used in order as the initial values of 
the AX, BX, CX, DX, BP, SI. and DI registers. Any registers 
with unassigned values vill be set to zero. 


The right argument contains the machine language 
routine to be executed. It can be an APL object of any data 
type, rank, or non-empty shape. 


The routine specified must conform to the following 
requirements: 


* It must terminate with either a far return 
instruction RET F (hexadecimal CB) or, to exit APL 
and return to the DOS environment (discarding the 
contents of the active workspace), with an INT 86hex 
instruction (hexadecimal CD 86). 


* It must return with the SS and SP register values 
the same as they were upon entry. 


* It must not use more than 498 bytes of stack depth. 
* It must be relocatable. 


* An offset of 10 bytes is needed at the beginning of 
the code if the code uses addresses that are 
relative to the offset of the beginning of the code. 
Jump and call instructions are relative to the 
current address in the program counter and therefore 
do not require the ten-byte offset. However, MOV 
instructions are sensitive to the beginning address 
of the code and therefore require the ten-byte 
offset. The easiest way to obtain the ten-byte 
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offset (origin OA hex) is to begin the assembler 
source code with ten NOPs, and then drop them (10+) 
from the binary code. A suggested procedure is to 
link the assembled code to make it a .EXE file, then 
convert it to a .COM file using the DOS utility 
EYE2BIN. Then, from APL: 


"MYPROG.COM' ÜNTIE 7i c 
ine + 104[WREAD ^1 82,UNSIZE 1 


routine + 
DNUNTIE ~1 
ÜCALL routine 


Result 


The explicit result of [CALL is a vector of the seven 
integer values of the same CPU registers as the left 
argument upon exit from the routine. 


Effect 


The registers are set to the values provided in the 
left argument (if any). DS is set to point to the start of 
the interpreter data segment, CS is set to point to the APL 
object in which the routine is stored, and IP is set to 
point to the first data byte within that object (for 
example, OAhex for a routine that uses addresses that are 
relative to the offset of the beginning of the code). Then 
the specified machine language routine is executed. If the 
routine ends with a far return instruction (hexadecimal 
value CB), the APL session in progress resumes. If the 
routine ends with an INT 86hex instruction, the APL session 
terminates (discarding the contents of the active workspace) 
and returns to the DOS environment. 


CAUTION: The use of [CALL with improperly constructed 
left or right arguments may result in a system crash, 
destroying the contents of the active workspace. 


For information on reserving CPU memory for 
user-vritten machine language routines, see the operating 
system manual for your computer. Note that, until the 
system is next bootstrapped, this technique reduces the 
workspace size in APL ([WSSIZE) by the amount that you have 
reserved. This reduction in [WSSIZE further prevents the 
loading of Workspaces with non-empty state indicators which 
were saved when BUSSIZE was different. 


The APL*PLUS/PC System includes a facility allowing a 
machine language routine invoked with (]CALL to assign a 
value to a variable already in the symbol table (named in a 
function or previously assigned). The routine invokes INT 
B8hex, after setting the registers to the following values: 


AR 
AL 


the desired rank of the object (0, 1, or 2) 

the number of bytes per element (1 for character, 
2 for integer, 8 for floating-point data) 

CX = the length along the first dimension (if any) 
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DX 
BX 


the length along the second dimension (if any) 
the symbol table pointer to the object to be 
assigned (the result of “STPTR) 


Upon return from this interrupt, an object of the 
specified type and shape has been created and assigned to 
the variable. unless an error has occurred. 


ES:DI points to the first data byte of the object, CX 
Shows the total number of elements in the object, DS is 
unchanged, and the other registers are undefined. The 
actual data stored in the object is undefined until data is 
moved into it after the use of INT 88hex. 


The values in ES, DI, and CX allow storage of data. 
For example, to set an array to zeros: 


SUB AX,AX 
REP STOSW 


The creation of the object may trigger a compaction of 
workspace memory, possibly causing the object containing the 
argument of CALL to move. If so, CS is adjusted and, upon 
return from the INT 88hex. CS:IP always points to the 
instruction following the INT. 


1f an error is encountered during execution of the 
interrupt, the rest of the execution of the machine language 
routine is abandoned. Control is returned to the APL 
interpreter, and the error is signaled as occurring during 
the execution of CALL. Possible errors include VS FULL 
when remaining space is insufficient for the object being 
created, LIMIT ERROR when the object would exceed 65,536 
bytes or have a dimension longer than 32,767, and DOMAIN 
ERROR when the name is not in the symbol table 
(O=[iSTPTR'NAME') or refers to a label or function. 


Note that while a workspace compaction causes objects 
to move in the workspace, the pointers returned by JSTPTR 
are still correct. [ISTPTR results point to a pointer (that 
may have changed its value) to the workspace object. 


A ÜCALL routine can use the APL*PLUS/PC System's input 
routine to get a character, if any, from the type-ahead 
buffer (the equivalent of [IINKEY with no wait) by performing 
a far call to [81]:(F1). This location is also described in 
"LPOKE -- Poke into CPU Memory". 


After the call, if the zero flag ZR is set, there is no 
character. If the zero flag ZR is clear (reset), the 
character is in the 4X register. The characters are 
returned as two-byte integers, with 0 in the more 
significant byte for "regular" (character) keystrokes, and 
255 in the more significant byte for "special" 
(cursor-movement) keystrokes. If a break or exit is 
detected, the ZR flag is set (that is, no character ready), 
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but the pending break or exit is indicated by the contents 
of location 165 (decimal). See "[POKE -- Poke into CPU 
Memory". 


A DOMAIN ERROR can be signaled by INT 0. (This 
simulates a divide-by-zero condition.) The APL interpreter 
will gracefully end executing the [CALL routine and signal 
the error to the calling environment. No other APL error 
messages can be signaled from a [CALL routine. 


INT 8Chex will clear off-screen scrolling memory. If 
AX contains 0. display attributes will not be saved in 

Subsequent scrolling. If AX contains 1, display attributes 
will be saved. All register values are lost during INT 8c. 
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If the [CALL routine invokes DOS 1/0 functions with INT 
21hex, errors that occur vill be intercepted by the DOS 
critical error routine and signaled in the APL environment 
as DRIVE NOT READY, DISK WRITE PROTECTED, or DISK ERROR, as 
appropriate. 


Examples 
0050000513 DCALL "13330 
00 p00 0 S13 [CALL CAVIDIO«238 203) 


In either form, this example is equivalent to 
performing a machine language routine 
consisting of the hexadecimal bytes EE CB, or 
in Assembly language 


OUT DX,AL 
RET F 


Since DX has been set to $13 (201hex), this 
fires the joystick one-shots, using the game 
control adapter. 


0 0 0 1020 LCALL LAVIDIO*236 52 1 238 203] 


This will reverse (raise or drop) the current 
status of DTR (Data Terminal Ready) on the 
COM1 communications line (serial port 1). It 
is equivalent to 


IN AL,3FCH 
XOR AL,1 
OUT 3FCH,AL 
RET F 


And, using the INT 88hex feature: 


CODE-DAV(OI0*205 136 184 3 0 243 171 203] 
(518, (ISTPTR 'NAME'),5 6) DCALL CODE 


This creates a 5-by-6 array filled vith 
threes. The machine language routine is: 


INT 88H ;AH=2, AL=2, BX=STPTR OF 'NAME', CX-5, DX-6 
MOV AX,3  ;DATA TO GO INTO THE ARRAY 

REP STOSW ;CX=30, ES:DI POSITIONED FOR STRING STORE 
RET F 


To erase an object from your assembler code: 


: Assume that BX contains the object's STPTR 
ES,[BX1,0 i Address variable 
MOV WORD PTR [BX],0 ; Mark symbol table undefined 
MOV AL,ES:BYTE PTR 6 ; type of object 
TEST AL,15 i Sets ZR if function 
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MOV ES:BYTE PTR 6,255 ; Mark object as garbage 


JNZ DONE 3; Done if variable 

MORE: MOV AX,ES:WORD PTR 7 ; Address next function line 
MOV — ES.AX 
OR AX,AX i ZR means end of function 
JZ DONE 


MOV ES:BYTE PTR 6,255 ; Mark fn line as garbage 
JMP SHORT MORE 
DONE: ... (Continue with your [CALL routine) 


The following longer example shows how APL utility 
function CSSMAT with an argument and an explicit result 
might be coded in assembler for faster execution speed. 


v M+CSSMAT V34;8;0I0 
1] a Consider 1*/ as the separator character that 
2] a divides Y into segments. Result M is a matrix 
3] a with a row for each segment. 
4] QIO-0 o +(12Mepy )pL1 © Aw (B+V=1pV)/1M © A-(144,M)-4 
5] MepAcAs.»3ii[/4 0 MeMp(Av ,AJVC-B)/V o ^0 
6) .— Li:iMe- (2t sV)oY 
v 
pTEXT-'/Start/middle of it/end." 


24 
PU-CSSMAT TEXT 
Start 
middle of it 
end. 
3 12 


JOFFE 
A»TYPE CSSMAT.ASM 


CODE SEGMENT BYTE 
ASSUME CS:CODE 
ASSUMES AX-STPTR OF ARGUMENT, BX=STPTR OF RESULT 
CHECKS FOR DOMAIN (CHARACTER), BUT NOT RANK 


SSMAT PROC FAR 
PUSE AX 
PUSH BX 


3 SAVE STPTR OF ARG 

3 SAVE STPTR OF RESULT 
MOV — BX,AX i PREPARE 70 ADDRESS ARG 
MOY ES,([BX] ; ES NOW ADDRESSES ARG 
MOV AK, ES:WORD PTR 6 ; RANK/TYPE OF ARRAY 


OR AE, AH 3 SCALAR IF ZERO 

JEZ | NOSCAL $ IE $0... 

CMP AL,1 3 CHARACTER? 

HA OKCEAR IF NOT, BIG TROUBLE 
INT 0 GENERATE DOMAIN ERROR 
MOV — CX,1 FOR 1 0 SHAPE OF RESULT 
NOV — DI,0 NUMBER OF COLUMNS 


MOV — A1,201H CHARACTER MATRIX 


POP BI 3 STPTR OF RESULT 
INT 88H MAKE IT 
POP AX 3 IGNORE ARGUMENT 


RET FAR RETURN 

NOSCAL: MOV — SI,8 POINTS TO LENGTH OF VECTOR 
LODS ES:WORD PTR [SI] ; GET THE LENGTH 
MOV — CI.AY 3 PUT IN COUNT REGISTER 
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EMPTY 


AL, 
BADDOM 


BX,BX 


cx 


ENDROW 
SHORT ONECHR 


ENDROW: CMP BX,DI 

JC  — NOLONG 

MOV — DX.B8X 
NOLONG: JCXZ  MAKEIT 

JMP — SEORT ONEROW 
DELIM: INC BP 

JMP SHORT ENDROW 
MAKEIT: POP BX 

MOV — AY,201H 

MOV — CX,BP 

INT — 88H 

POP BX 

MOV — DS.LBX] 

MOY — SI,8 

LODSW 

MOV — CX.AX 

MOV — D1,12 

LODSB 

MOV — AH,AL 
EACHRO: MOV DY .ES:WORD PT. 

SUB BX, BX 
EACECE: LODSB 

DEC CX 

CHP — AL.AE 

JNZ — NODELI 
LASTRO: PUSH CX 

MOV — CY,DX 

$UB — CY,BX 

JCYZ NOFILL 

MOV AL," ' 

REP — STOSB 
NOFILL: POP CX 

JCXZ  ALLDON 

JMP SHORT EACHRO 
NODELI: JCXZ LASTRO 

STOSB 

INC Bx 

JMP SHORT EACECH 
ALLDON: RET 
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AX,ES:WORD PTR 6 


GO MAKE EMPTY MATRIX IF 0 
3 CHECK FOR CHAR. TYPE 
IF NOT... 


3 GO REPORT ERROR 


ES:BYTE PTR [SI] 


ESiBYTE PTR [ST 


3 GET THE DELIMITER 

ONE LESS CRAR TO COUNT 
SINGLE ELEMENT SPEC. CASE 
FOR COMPARISON 

INITIALIZE DELIMITER COUNT 
ZERO LONGEST-ROW COUNT 
ZERO CURRENT-ROW COUNT 

l : GET A CHARACTER 
DECREASE CHARACTER COUNT 


1 1$ IT THE DELIMITER? 
; IF SO, CHECK OUT TEE LINE 
i BUMP CURRENT-ROW COUNT 


END OF WHOLE OBJECT? 
IF NOT, GO GET ANOTBER CHAR 
IS THIS A NEW LONGEST-ROW? 


3 IF NOT, FORGET IT 


IF $0, NEW LONGEST-ROW 
MAKE RES. IF ALL CHARS USED 
IF NOT, GET ANOTHER ROW 
BUMP DELIMITER COUNT 

GO DEAL WITH END-OF-ROW 
STPTR OF RESULT 

CHARACTER MATRIX 

NUMBER OF ROWS (DX HAS COLS) 
MAKE IT 

STPTR OF ARGUMENT 

DS ADDRESSES ARGUMENT 
POINTS TO DIMENSION OF ARG 
GET THE DIMENSION 

COUNT (WE KNOW IT'S NOT 0) 
START OF DATA IN RESULT 
GET THE DELIMITER 

SAVE, FOR COMPARISON 

10 ; LENGTH OF RESULT ROW 
NUMBER XFERRED IN THIS ROW 
GET A CHAR 

BUMP COUNT DOWN 

DELIMITER? 

IF $0... 

SAVE THE TOTAL CHAR COUNT 
LENGTH OF ROW 

THE DEFICIT (FILLER COUNT) 
0 MEANS FULL ROV. SKIP IT! 
PREPARE TO STORE SPACES 
STORE 'EM 

RETRIEVE TOTAL COUNT 
FINISHED IF ALL CHARS USED 
IF NOT, DO ANOTHER ROW 
END OF LAST ROW. FILL IT, 
TRANSFER THE CHAR 

BUMP NUMBER-XFERRED COUNT 
GO GET ANOTHER CHAR 

FAR RETURN 
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SSMAT — ENDP 
CODE ENDS 


END 
A»ASM CSSMAT . ASM 
A>LINK CSSMAT; (1gnore "WARNING: NO STACK" message.) 
A>EXE2BIN CSSMAT 
A» APL 
«++ (APL session startup banner) ... 
"CSSMAT.BIN' ONTIE 1 x 
CSSMATMLCODE- NREAD ^1 82, NSIZE “1 


INUNTIE 1 


y M-CSSMATML Y 
(1] a Consider 1*V as the separator character that 
[2] a divides V into segments. Result M is a matrix 
(3) ^ with a row for each segment. 
[4] Ve,v o v-(STPTR 'V M') CALL CSSMATHLCODE 

v 


CSSMATML TEXT 


Start 

middle of it 

end. 

3 12 (CSSMATML runs much faster than CSSMAT.) 


Error Reports 


DOMAIN ERROR The left argument is not integer-valued 
or contains values out of range for the 
respective registers. 


LENGTH ERROR The right argument is empty. Or, the 
left argument is longer than seven 
elements. 


WS FULL The explicit result requires more 


Storage than is available in the 
workspace. 
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Specifying the Capture Sink (leap 


The monadic system function ICAP is used to specify a 
capture sink, and indicates the success of the capture Sink 
specification or the reason for failure. “CAP, as described 
here, is specific to the APL*PLUS/PC System; it may be 
different or absent in other APL*PLUS Systems. 


Syntax 
result + [CAP 'sink' 
result - the explicit result 


sink - a Character vector or singleton describing the 
capture sink to use 


Argument 


The argument to ICAP is a character singleton or vector 
that specifies a component file to be used as a capture 
sink. An empty argument means do not capture input and, in 
effect, turns off a capture sink. The form of the argument 
is 


‘library filename reservation :passnumber' 


library The library number of the file, 
optional. 

reservation Used to resize an existing file or to 
set the reservation for a file that is 
to be created, optional, 

passnumber A file passnumber (if the file already 
exists), optional. 


Result 


The explicit result of [CaP is an integer scalar that 
indicates the success or failure of the specification: 


Result Meaning 


1 Specified capture sink successfully established. 

2 Unable to interpret specification. 

3 11l-formed passnumber. 

10 FILE NAME ERROR (name is ill-formed, or a 
passnumber is specified for a non-existent 
file). 

11 FILE TIED (with DWTIE). 
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12 


13 


17 


25 

27 

28 

29 

30 

31 

32 

33 
Effect 

The spe: 
line of inpu 
pressed. Th 
from the exei 


ICAP allows 
replacing th 


FILE ACCESS ERROR, one of the following 
meanings: 


File exists but the user account number in use 
does not have append access. 


File exists and reservation specified, but the 
user account number in use does not have resize 
access. 

File exists but the wrong passnumber is 
specified; if the file is already tied, the 
passnumber associated with the current tie must 
be used. 

FILE DAMAGED. 

FILE SIZE ERROR, file reservation specified is 
smaller than the amount of space already used by 
the file. 

FILE TIE QUOTA EXCEEDED. 

DRIVE NOT READY. 

DISK ERROR. 

DISK FULL. 

DIRECTORY FULL. 

DISK WRITE PROTECTED. 

LIBRARY NOT FOUND. 


INSUFFICIENT HANDLES. 


cified file is tied or created. Each subsequent 
t is captured as a component when Enter is 

e lines are executed immediately, but no output 
cution is recorded in the capture sink file. 
easy creation of a file for later use with CIN 
e user at the keyboard. 


Error Reports 


RANK ERROR 


DOMAIN ERROR 


WS PULL 


Copyright 19 


The argument is not a singleton or 
vector. 


The argument is of proper rank but is 
nót character valued. 


The explicit result requires more 
workspace storage than is available. 
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The following errors may occur while using a file 
capture sink, and result in the diagnostic message being 
written to the output sink in use but not recorded in []DM; 
DELY is not executed; any capture sink in use is switched 
off, but any file output sink remains in effect; input 
reverts to the keyboard and output to screen resumes if it 
was off. 


ÜCAP DISK ERROR A disk error has occurred during 
the attempt to append to the 
capture sink file, probably due 
to a hardware fault on an 
unformatted or defective disk. 


ICAP DISK FULL Recording the most recent input 
would require more space than is 
currently available on the disk. 


DCAP DISK WRITE PROTECTED The disk now in the disk drive 
where the capture sink file is 
expected has a protective cover 
over the notch preventing any 
alteration of its contents. 


DCAP DRIVE NOT READY The disk drive that should 
contain the capture sink file is 
not ready for use, possibly empty 
or with its door open. 


ÜCAP FILE DAMAGED The capture sink file has invalid 
values in its component 
directory, possibiy from having 
replaced the disk while the file 
was tied. 


ÜCAP FILE FULL Recording the most recent input 
would exceed the file reservation 
of the capture sink file. 


DCAP FILE TIE ERROR The capture sink file has been 
erased from DOS using OCMD. 


Side effects from other errors or interrupts: input reverts 
to the keyboard, and screen output is added to any output or 
capture sinks in effect, if a file input source is exhausted 
or if the system encounters a strong interrupt, an untrapped 
error (including system command errcrs), a trapped error 
where DELX cannot be executed, a trapped error where DELY 
does not restart execution by a branch or by executing 
DERROR, or a weak interrupt where TALX cannot be executed or 
where its execution does not restart execution. 
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Mw Execute DOS Command OCHD 

The monadic system function [CMD executes the command 
given to it from the DOS environment, and returns to resume 
APL execution in the workspace. JCMD, as described here, is 
specific to the APL*PLUS/PC System; it may be different or 
absent in other APL*PLUS Systems. 


Syntax 
result + ICMD command 


result - the explicit result 

command - a character singleton or vector of up to 128 
characters representing the DOS command to be 
executed 


Argument 


The argument to ICMD is a character vector or singleton 
representing the DOS command to be executed. 


Result 


The explicit result of the system function [CMD is an 
empty matrix of shape 0 0 unless there vere files tied 
before execution that cannot be retied after execution. 
Failure to retie files could result from removing a disk, or 
from renaming or erasing a file from DOS. If the automatic 
retying of files is incomplete, the explicit result of (CMD 
is the character vector "COULD NOT RETIE ALL FILES". 


Effect 


The effect of “CMD is to temporarily exit from APL 
while preserving the contents of the active workspace and to 
execute the command given in the argument from DOS (which 
could be running non-APL software like a word processor or 
Spread-sheet program), and then return to APL and execute 
any following APL code in the statement containing [CWD. 
The system status line, if it was on, is turned off for the 
duration of the DOS session. 


If the argument to [ICMD is an empty vector ([]CMD ''), 
the effect is to load the DOS command interpreter from disk 
into available space in the workspace, and allow any number 
of DOS commands to be typed from the keyboard before 
returning to APL by entering the command: 


A>EXIT 
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The DOS command processor file, COMMAND.COM, is loaded 
from disk, and a disk containing this file must be present 
in the disk drive specified by the DOS COMSPEC- parameter. 
To see this DOS parameter, execute the command SET from DOS, 
or execute )CMD SET from APL. Note that the COMSPEC- 
parameter cannot usefully be set during a )CMD session 
because such a session lasts only until the exit from DOS 
back to APL. 


While the DOS command interpreter is in use, the 
keyboard reverts to the standard DOS keyboard: for example, 
in the positions of the : and | characters and in the need 
to use the original Ctrl key vith NumLock or Break. Also, 
while the DOS command interpreter is in use, all files are 
untied. If possible, they are retied to the same numbers 
upon return to APL; if not (such as when a disk with tied 
files has been removed), the message COULD NOT RETIE ALL 
FILES is returned. 


DOS commands produce their normal outputs. To capture 
such output from APL, you can have DOS direct the output to 
a file from which APL can then read it with GWREAD, or you 
can use [WGET to capture it from the screen. For example, 
the following program will capture the DOS output from a 
particular command: 


Y ReCAPTURE COMMAND S 
(1)  DCMD COMMAND,'»SCRATCH.TMP' o 'SCRATCH.TMP' [NTIE “1 
[2] — R«DWREAD 1 82 ,ONSIZE 1 © Re(R#LTCLE)/R 
[3] — 'SCRATCH.TMP' ONERASE 

y 


You can also get the return code of a program invoked 
with ICMD once back in APL by using 1119712 DINT 33. The 
return code for all DOS utilities is zero. 


If an error is encountered during the execution of a 
DOS command under DCMD, DOS will report the error, and 
CORTO returns to APL, The DOS error is not recorded in 
IDM. 


If a non-APL routine executed via [CMD (or )CMD) leaves 
the cursor outside of the current window, upon return to 
APL, the cursor moves to the beginning of the current 
window. 


WARNING: The session buffers for (1) keyboard 
type-ahead and (2) the buffered serial port (COMi by 
default) are not preserved during UCMD or )CMD. Typing 
ahead for APL cannot, therefore, be done during OCHD, and 
LCMP should not be used during concurrent I/O transfer. 


Copyright 1983 STSC, Inc. 3-26 System Functions 


The off-screen scrolling memory and current screen are 
preserved by using this function to execute the DOS command: 


Y ReSCREENSAVECMD DOSCOMMAND;CURSCRNiOSSMP;0SSM; IOi')SEG 
l a Save current screen and off-screen scrolling memory, 
] a "OSSM", while executing a DOS command with CMD. 
l a Limited to S=32 thousand bytes of screen memory. 
] ^ For use with Release 3.0 or later releases. 
Jl USEG+10 o DI0-0 o OSSMP-LPEEK 180+.% a OSSM parameters 
l1  ÜUSEG-25617PEEK 137 136 a Find OSSM address segment 
]  OSSM-«)PEEKi-CRT[O]«34CCRT[S ])x1«GCRTÍ3] a Save OSSM data 
1  CURSCRN- O O 25 80 [WGET 5 a Save current screen data 
ui 
D 
X 
2 
3 


R-CAPTURE DOSCOMMAND a Use function that captures DOS 
] a output as an explicit result using a native file 
1 0 025 80 “WPUT CURSCRN a Restore current screen data 
] 0 0 pOSSM -POKEi.CRT[O]x3480x1« CRT[3] a Restore OSSM 
1 [SEG-'' o 0 0 pOSSMP SPOKE 180+14 r and OSSM parameters 
v 


A DOS command in the argument to CMD, or any DOS 
commands that are entered in DOS command level during the 
execution of CMD '', are executed as if in a machine whose 
total memory equals the sum of the WA in the workspace at 
the time of execution, together with the memory devoted to 
the buffers for type-ahead off-screen scrolling, and 
communications. If this does not provide sufficient space 
to load the DOS command interpreter, a W$ FULL is reported. 
Thus, depending on the amount of memory installed in your 
personal computer, you can invoke the APL«PLUS/PC System 
from within itself by CCMD 'A4PL' to a depth of several o 
levels, but with a smaller workspace at each level. In such 
a case, the system command )0FF returns to the system from 
which the running APL system vas activated and resumes 
execution. 


Examples 

Temp 'DIR' (Displays on the screen a DOS 
directory of the disk in the 
current default disk drive.) 

DCMD ‘FORMAT B: /1' (Prompts for insertion of a 
disk in disk drive B, and 
formats it as single-sided.) 

ZCMD 'BASICA MYPROG' (Runs the BASIC program 
MYPROG.) 

ocup '* (Enters the DOS command level 
until Exit is entered.) 

ÜCMD 'MODE COM1:12" (Sets the communications speed 


on the first serial port to 
1200 baud.) o 
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Error Reports 
DOMAIN ERROR 


DOS COMMAND FILE NOT FOUND 


DRIVE NOT READY 


LENGTH ERROR 


RANK ERROR 


WS FULL 
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The argument contains numeric 
data. 


The DOS system disk is not 
loaded, or the COMMAND.COM file 
cannot be found in the path 
specified by the DOS COMSPEC- 
parameter. 


The disk drive expected to hold 
the DOS command interpreter 
(according to the DOS COMSPEC- 
parameter) is not ready. 


The argument is longer than the 
123-character DOS maximum. 


The argument is not a vector or 
singleton. 


There is not sufficient space 


available to load the DOS 
command interpreter. 
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QCOPY -- Copy from Saved Workspace, with Replacement (COPY 


The ambivalent system function COPY can copy a list of 
APL functions and variables (but not labels) from the local 
environment of a saved workspace into the active vorkspace 
Or can copy all functions and variables in the saved 
workspace into the active workspace, replacing objects vith 
the same name(s) in the local environment of the active 
workspace. 


Syntax 


result - —— copr wsid 
result + obilist ICOPY wsid 


result - the explicit result 


wsid ^ - a character vector or singleton containing a 
workspace name, optionally preceded by library 
number 


obilist - a character vector, singleton, or matrix 
containing a list of functions and variables to 
be copied 


Argument 


The optional left argument to “COPY is a list of 
objects to copy into the active workspace. It can be a 
Character singleton, a character vector with one or more 
Spaces between object names, or a character matrix with one 
name per row. If the list is empty, nothing is copied. 


If no left argument is given, all objects are copied. 


The right argument to (COPY is a character vector or 
Singleton containing the identification (optional library 
number and name) of the saved workspace from which to copy. 
If no library is specified, the current default library is 
assumed. 

Resul 


The explicit result of COPY is an integer vector 
representing the success or failure of the copying 
operation. 


If dyadic ICOPY was used, the explicit result includes 
one integer for each name in the list, indicating success or 
failure in copying that object. The folloving codes are 
used: 


2 - a variable by the specified name was successfully 
copied 

1 - a function by the specified name was successfully 
copied 

0 - no object by the specified name was found, or the 
specified name appeared earlier in the copy list 

2 - object was too large for available space in the 
active workspace 
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73 - cannot copy while name is defined as a label or as 
a pendent, suspended, executing, or waiting 
function 

4 - not enough space in symbol table (no objects have 
been copied) 

6 - no space to compare symbol tables or to store long 
names that are in the list or used in functions in 
the list. 


If monadic ICoPY is used, an empty result indicates a 
completely successful copy of all the objects in the saved 
workspace. If one or more objects were functions in the 
state indicator, the result is a numeric vector using the 
same error codes. 


1f an unanticipated error occurs, no explicit result is 
returned (see "Error Reports", below). 


Bifect 


The objects, if found in the local environment of a 
saved workspace of that name, are copied into the local 
environment of the active workspace. The explicit result 
indicates whether they are functions or variables, and 
whether any objects were not found or not copied. 


ÜCOPY will replace an object by the same name already 
in the active workspace. Thus, its effect is similar to 
that of COPY. 


Copying a function removes any LisToP and [TRACE 
settings for it in the saved workspace. 


The time required to complete a copy operation is 
dependent more on the size of the workspace named in the 
copy command than on the size of the items in objlist. Copy 
times of over one minute are common when the workspace 
Stored on disk grows as large as 100,000 bytes. See "Hints" 
in the Programmer's Manual for suggestions about saving time 
by avoiding copying objects into the active vorkspace. 


Example 
)VARS 
MATRIX 
MATRIX 
12 
34 
IST 
SUSPENDED3]* 
MATRIX XXX DATA SUSPENDED' [COPY 'W$3" 
20273 
VARS 
DATA MATRIX 
MATRIX 
CAT 
DOG 
RAT 
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Error Reports 


DISK ERROR 


DOMAIN ERROR 


DRIVE NOT READY 


INSUFFICIENT BANDLES 


INVALID WS NAME 


LIBRARY NOT FOUND 


RANK ERROR 


WS FULL 


W$ NOT FOUND 


A disk error has occurred, probably 
due to a hardware fault or to an 
unformatted or defective disk. 


One argument is not character-valued, 
or the left argument contains an 
ill-formed APL identifier (object 
name). 


An attempt has been made to use an 
empty or non-existent disk drive. 


The maximum number of files that DOS 
allows open at one time would be 
exceeded. If you can untie a file, 
you can free a handle for the 
attempted operation. To increase the 
number of handles available, include 
FILES=n (where n is 5 more than the 
desired file tie quota) in your 
CONFIG.S$YS file and reboot the 
system. For the default file tie 
quota of 10, use FILES-15. 


The right argument contains an 
ill-formed workspace identification. 


The APL library (DOS directory) you 
are trying to use cannot be found on 
the disk in the disk drive indicated 
by L788. Failure to find the 
library may result from not including 
a space between the library number 
and workspace name. 


A non-singleton left argument has a 
rank greater than 2, or a 
non-singleton right argument has a 
rank greater than 1. 


There is not enough space in the 
workspace for the explicit result. 


No workspace by that name is 
currently in the specified or default 
library. 
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DECR -- Canonical Representation of a Function BER 


The monadic system function ()CR returns the canonical 
representation of the most local definition of a function. 


x 
result + DCR fnname 


result - the explicit result 
Ínname - the function name 


Argument 


The argument to DCR is the character representation of 
one function name. It can be represented as a character 
singleton or vector. 


Result 


The explicit result of DCR is a character matrix 
containing the canonical representation of the function; 
that is, no leading or trailing del symbols (v) or bracketed 
line numbers appear. Each line of an APL function 
(including the header) is left-justified in the 
corresponding row of the matrix, and all lines except the 
longest line of the function are padded on the right with 


blanks. 

o 1f the argument is a character singleton or vector but 
does not represent the name of an unlocked function, the 
result is an empty matrix with shape 0 0. 


Example 
Y TRI Ni 
[1] Dede, 
[2] +(W<pd)p0 o D-A+(0,A)+A,0 o +DLC 
v 
pQ«UCR "TRI 
332 
a 
TRI N3A 
De. 
>(N<pA)p0 © De4-(0,4)*4,0 0 »DLC 
Error Reports 
DOMAIN ERROR The argument has the proper rank but is 
not character-valued. 
e@ RANK ERROR The argument is not a vector or singleton. 
WS FULL The explicit result requires more 


workspace storage than is available. 
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OcRL -- Single Function Line Display Ocrt 
The monadic system function [CRL returns a character 


vector containing the canonical representation of a single 
line of the most local definition of a function. o 


Syntax 
result + OCRL ‘fnname[n]" 
result - the explicit result 
fnname - the function name 
n - the function line number 
argument 
The argument to DCRL is a character vector of the form 


‘fnname[n]' where fnname is a function name and n is a 
non-negative integer. 


Result 
1f n corresponds to a line number in the function named 
fnname, the explicit result of DCRL is the canonical 


representation of line n of the function. If n is zero, the 
result is the header of the function. 


greater than the largest line number of the function, the 


If fnname is the name of a locked function, or if n is 
result is an empty vector. e 


If the argument is ill-formed, the result is an empty 
vector. The following conditions can cause this: 


e The specified name is not a function. 
* The brackets are omitted. 


* Extraneous non-blank characters exist in the 
argument. 


* n is negative, non-integral, or greater than 9999. 


Exampie 
eU-DCRL "TRIUi]* (Function TRI is defined in 
the example for "OCR -- 
Canonical Representation of 
a Function.) 
Üec4-,.1 
6 
pD + (UER 'TRIDI2;] (DCR can also be used.) 
—- E 
32 
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Error Reports 


DOMAIN ERROR The argument has the proper rank but is 
not character-valued. 


[m ERROR The argument is not a vector or singleton. 


WS FULL The explicit result requires more 
workspace storage than is available. 
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RLPC -- Publi mment Display DenLPC 
The monadic system function OCRLPC returns a character 
vector containing the canonical representation of a public 
Comment from a single line of the most local definition of a 
function. A public comment is one beginning with a? and E 
occur on the same line as code that is to be executed. 
DCRLPC operates even on locked functions. 


Syntax 
result + (CRLIPC 'fnname[n)' 
- the explicit result 
inname - the function name 
n - the function line number 
Argument 
The argument to [CRLPC is a character vector of the 
form 'fnnameín]' where fnname is a function name and n is a 
non-negative integer, 
Result 
If n corresponds to a line number in the function named 
fnname, the explicit result of [ICRLPC is the canonical 
representation of the public comment, if any, on that line. 
If there is no public comment on line [n], or if n is o 
greater than the largest line number of the function, the 
result is an empty vector. 


1f the argument is ill-formed, the result is an empty 
vector. The following conditions can cause this: 


* The specified name is not a function. 
* The brackets are omitted, 


e Extraneous non-blank characters exist in the 
argunent. 


* n is negative, non-integral, or greater than 255. 
Example 


DCRLPC 'LOCKEDFN[1]' 
^" THIS FUNCTION IS LOCKED TO HIDE A FILE PASSNUMBER. 


Error Reports 


DOMAIN ERROR The argument has the proper rank but is 
not character-valued. e 


WS FULL The explicit result requires more 
workspace storage than is available. 
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RT =~ 


r; 


la: nformation Ocrr 


The niladic system function [CAT produces a seven- 
element integer vector of information about the current 


tate of the screen memory. [CRT is experimental in this 
elease of the APL«PLUS/PC System; it may be different, 
absent, or replaced by an entirely different feature in a 


subsequent release. 


Syntax 


result + DCRT 
result - the explicit result 


Result 


The explicit result of [CRT is a seven-element numeric 
vector containing the following information about the state 
of the screen memory: 


Uu 


[53 
[6] 


Effect 


number of lines that off-screen memory can hold 
considering the screen size and attribute 
selections in use (these can be set as a 
startup option -- see “Beginning and Ending an 
APL Session from DOS" in the User's Guide) 


number of lines above those currently on the 
screen 


number of lines below those currently on the 
screen 


whether attributes are (1) or are not (0) saved 
with off-screen lines 


how many lines the screen can hold 


how many columns the screen can hold on a 
single line 


CRT mode (black-and-white refers to the color 
monitor as opposed to monochrome): 


0-40-column black-and-white character 
1=40-column color character 
2=80-column black-and-white character 
3=80-column color character 
7=80-column monochrome character 


DCRT prepares its explicit result as of the moment it 
Any subsequent output to the screen, including 
displaying the [CRT result, is likely to alter the state of 
the screen memory reported by DCRT. 


executes. 
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System Functions 


Entering graphics mode with [¢IWIT does not change the 
mode reported by (CRT. 


Examples 


A e 

S8 0 0 0 25 807 (There are 98 lines of available 
off-screen memory, but there is not 
currently anything above or below what 
is showing on the screen; attributes are 
not preserved off screen; the screen has 
25 lines, 80 columns, and is an IBM 
monochrome monitor.) 


Ocrr 
49 40 8 1 25 401 (There are 49 lines of off-screen memory 

available, with 40 lines in use above 
the screen, and 8 scrolled back below 
the screen; the color attributes are 
preserved off screen; the screen is 25 
lines, 40 columns, and is a color 
monitor or is behaving like one.) 


Error Reports 


WS FULL There is not enough room in the workspace 
for the explicit result. 
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fe? -- Comparison Tolerance ner 


The workspace-related system variable [C7 is the 
maximum relative difference allowed between two numbers if 
they are to be considered equal. It is used to overcome the 
problems of inexact internal representation and cumulative 
rounding errors that are inherent in computer arithmetic on 
noninteger values. Comparison tolerance is a means of 
ignoring small differences between two numbers which are 
likely to come from these two causes. 


Inexact representation results from the fact that 
numbers are entered in base 10 (decimal) although floating- 
point numbers are represented with 64 binary digits (bits) 
in base 2 -- 52 bits for significand, 11 bits for exponent, 
and one sign bit. For example, because the representation 
of 0.1 in base 2 is a nonterminating sequence of binary 
digits, 0.1 cannot be represented exactly. 


A rounding error can occur when the result of a 
calculation cannot be represented exactly, and thus the last 
significant digit in the calculation is rounded. 


Domain 


The domain for assignment to [CT is any numeric 
Singleton with a value less than 2* 13 but not less than 0. 
The value assigned to GCT in the APL*PLUS/PC System is 
rounded down to the nearest negative integral power of two 
before being stored. 


Valve when Referenced 


When iC? is reference 
from 0 to 2» 14, inclusive. 


Default value in a Clear Workspace 


In a clear workspace, the default value for JC? in this 
system is the negative 46th power of 2 (2* 18) or 
approximately 1.48714. See the chart presented in "Effect", 
below, before setting OCT to zero (to yield greater 
execution speed for the primitive functions that depend on 
the value of ICT). 


ÜCT-Dependent Primitive Functions 


The value of ICT is used when computing the result of 
any of the following ten primitive functions when used on 
floating-point data: 


its value is a numeric scalar 


* floor (monadic |) 


* ceiling (monadic [) 
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* residue (dyadic |) 
* match (dyadic =) 

* membership (dyadic «) 

* index of (dyadic i) 

* numeric relationals (dyadic < s = > > #) 


* find (p. 


DCT is a relative comparison tolerance. When two 
numbers are compared and at least one of them is a 
floating-point number, their relative difference (which 
depends on their magnitudes) is compared against “CT. Two 
numbers are considered equal if their relative difference is 
less than or equal to CT. Other comparisons are derived 
from that property. 


The test for equality of 4 and B from a mathematical 
point of view is 


CIA-B) SiCT* CIADFIB 

If ICT is 0, all comparisons are exact. Furthermore, 
all comparisons vith the number 0 are exact, and are 
independent of "CT. 


The following chart shows how the results of some 
simple expressions depend upon the value of CCT. 


EPS +> 1875 
4 +e 0 o 1 1 
B ++ (0+EPS),(0-EPS?,(1+EPS),(1-EPS) 
-0 1B ++ 0 7i 1 o 
~ 10xEPS tg +> 0 o £ 1 
+0 [B e i o 2 1 
+ 10xEPS [B - 0 o 1 1 
der - 0 A=B e» 0 o o o 
JC? + 10xEPS 4A:Bo- 0 o 1 1 
ECT + 0 A<B - d 0 1 o 
Cer + 10xEPS ACB e 1 o 9 0 
-0 AB e 5 5 5 5 
+ 10xEPS AB 5 5 3 3 
+0 Ao 0 o o o 
+ 10xEPS AB 0 o 1 1 
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Examples 


Der 
1.421085472E 14 (the default value) 
4*-(011)*01 
e. : 
11 
4l 
1 
T4 
1i 
Dcr«o 
4211 
9 
[A 
12 
4-11 
1.7763568395715 
Error Reports 
DOMAIN ERROR The value being assigned to DCT is a 
singleton whose value is either negative 
or greater than or equal to 2« 13. 
RANK ERROR The value being assigned to OCT is not a 


singleton. 
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sor P. n Ocursor 
The session-related system variable [CURSOR contains 

the current location of the cursor within the current window 

on the screen. Its value is a vector containing the row and, 

column of the current cursor position relative to the upper ( J 

left corner of the window in use (see "[WINDOW -- Window 

Specification"). CURSOR, as described here, is specific to 

the APL*PLUS/PC System; it may be different or absent in 

other APL*PLUS Systems. 


Domain 


The domain for assignment to DCURSOR is a positive 
integer vector of length 2 whose elements are less than the 
current window size ( 2*(WINDOW) respectively. The domain 
of DCURSOR is not limited by the current setting of the 
printing width (Sew). 


Value when Referenced 


When DCURSOR is referenced, its value is a vector of 
two integers within the domain. These represent the current 
position of the cursor within the current window, expressed 
as row and column numbers in origin 0 (see "DIO -- Index 
Origin"). 


val i r 


The default value for [CURSOR is 0 0. This value 
re-appears each time the window is cleared or respecified to 
a value not including the current cursor position, or when 
returning to an earlier global value causes the cursor to 
move outside the current vindow. 


Effect 


The effect of assigning a new value to [CURSOR is 
moving the position of the cursor to the new position within 
the window described by the new value. 


The effect of referencing DCURSOR is to return the 
cursor location at the time that the reference is executed 
(not its position before the line was executed). 


Examples 
Gcursor 
12 0 (The cursor vas on line 
12 in column 0 of the 
current window when 
DCURSOR was executed.) e 
DCURSOR + 0 0 9 ‘at (Move the cursor to the 


upper left corner of the 
current window and 
display an "4".) 


Copyright 1983 STSC, Inc. 3-u1 System Functions 


Error Reports 


DOMAIN ERROR The value being assigned to [CURSOR 
describes a position outside the current 
window (as measured from the window's 

o upper-left corner). Or, the value is 
non-integral, containing characters or 
fractional numbers. 


LENGTH ERROR The value being assigned to DCURSOR is a 
vector but does not have two elements. 


RANK ERROR The value being assigned to DCURSOR is a 
scalar, a matrix, or a higher-dimensional 
array. 
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OpsE_-- Function Definition Ober 


The monadic system function DDEF defines a function 
from either the canonical or the visual representation of 


the function. e 
Syntax 


result + DDEF inrep 


result - the explicit result 
fnrep - the character representation of a function 


Argument 


The argument to [DEF is a character vector or matrix 
Containing the character representation of a function. 


The rank of the argument (1 or 2) determines which of 
the following two sets of rules are used to define the 
resulting function: 


(1) Result of DYR. 


Note, however, that while [VA cannot display a locked 
function, [DEF accepts vector arguments with a leading 
or trailing *, and locks the resulting function. 


(2) Result of DCR. e 


With either a vector or a matrix argument, (DEF ignores 
blanks that would be superfluous in keyboard entry of a 
function. 


Result 


If the function definition is successful, the explicit 
result of [DEF is a character vector containing the name of 
the function defined. 


1f the function definition is not successful, the 
result is a two-element numeric vector containing 
information about the error (see "Error Reports", below). 


Effect 


Unless an error condition occurs, a function of the 
appropriate name is defined in the active workspace. The 
amount of available workspace area and the number of symbols 
may change. 


local identifier in a currently executing, pendent, or 
suspended function, the newly defined function is local to 
that function and is erased when the function in which it is 
localized completes execution. 


1f the name of the function defined corresponds to a [ ] 
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1f the name of the function defined corresponds to the 
name of an existing function, the existing function is 
replaced and any [STOP or [IPRACE settings in the function 
are removed. 


xampl 
MeDCR 'TRI' 
M[iile(1spM)t'TRIANGLE N;4* 
ODEF M 

TRIANGLE 


Error Reports 


DOMAIN ERROR The argument has the proper rank but is 
not character-valued. 

RANK ERROR The argument is not a matrix, vector, or 
singleton. 

WS FULL The explicit result requires more 


workspace storage than is available. 


1f the system recognizes an error condition during 
analysis of argument values, the function is not defined, 
but no explicit error is reported. Instead, the result is a 
two-element integer vector containing information about the 


error. 


The first element is the type of error that 


occurred; the second element indicates the row of the matrix 
argument or the element of the vector argument at which the 
line containing the error begins. The index returned 
depends upon the value of DIO. 


The following error types are indicated by the first 
element of the result: 


1 


WS FULL; the function definition requires more 
workspace storage than is available. 


2 - DEFN ERROR; the header is ill-formed, or the 
function name is in use as a variable, label, 
executing, pendent, suspended, or waiting function. 

3 - (reserved) 

4 - SYMBOL TABLE FULL; the function definition would 
exceed the number of symbols available in the 
symbol table. 

5 - UNMATCHED QUOTES; the argument contains an odd 
number of quotes outside comments, 

6 - (reserved) 

7 - (reserved) 

8 - (reserved) 
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9 - LIMIT ERROR; the argument contains the character 
representation of a number whose absolute value 
exceeds 1.7976931348623165308. 

Comparison of [DEF with DFX 


ObEF and DFY provide similar capabilities. The e 
differences are listed below: 


* (DEF accepts both canonical (matrix) and visual 
(vector) representations of a function; DFI accepts 
only the canonical representation. 


* ‘WEF can create a function as a locked function; DFY 
cannot. 


* DDEF indicates both the cause and the location of an 
error; [FX indicates only the location. 
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zz Sin Function Lin: itin UDEFL 


The monadic system function DDEFL allows editing of a 
single line of the most local definition of an unlocked 


elete, replace, or insert a single line of a function, or 


Qa: Depending on its right argument, QDEFL can 
di 


lelete multiple lines. 
Syntax 
result + DDEFL argument 


result ~ the explicit result 

argument - the function name and line number being 
edited, followed by a line to be inserted or 
replaced 


Argument 


To delete multiple lines in the function named fnnane, 
argument has the form 'fnname[-n n n]' where the n's are 
zero or more line numbers to be deleted. To delete one 
line, argument has the form 'fnname[-n]' where n is the 
number of the line to be deleted. ([IDEFL cannot delete the 
function header, line [0]. 


To replace an existing line in the function named 

by the line given as ling. the argument has the form 
"fnname[nlline' where n is the number of the line to be 
replaced. 


To insert a new line given as line into the function 
named fnname, arqument has the form 'inname[nlline'. If n 
is fractional, the nev line is inserted after line number lp 
of the function. If n is greater than the largest line 
number of the function. the new line is inserted at the end 
of the function. 


Result 


1f the operation is successful, the explicit result of 
ÜDEFL is a character vector containing the name of the 
function. If the name of the function changes as a result 
of replacing line [0] of the function, the result is the 
name of the new function. 


If the operation is unsuccessful, the result is a 
numeric scalar containing information about the error (see 
"Error Reports", below). 


Effect 


After an insertion or deletion, all lines following the 
point of insertion or deletion are automatically renumbered. 
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Note that the form of the argument to [DEFL is the same 
for insertion and replacement. The effect depends on the 
value of n relative to the line numbers of the function. In 
this sense, the behavior of [JDEFL is similar to the editing 
capabilities in function definition mode. e 


Example 


Using the function TRI defined in "DCR -- Canonical 
Representation of a Function": 


A-ÜCRL 'TRI(2]'! 9 ALArt+* jetz’ 
OVR DDEFL 'TRII2]',4 


v TRI NA 

[1J O4. 

[21 >(N<pA)/0 o [Ie4-(0,4)24,0 o +0LC 

v 

Error_Reports 

DOMAIN ERROR The argument has the proper rank but is 
not character-valued. 

RANK ERROR The argument is not a matrix, vector, or 
singleton. 

WS FULL The explicit result requires more space 


than is available. 

If the system recognizes an error condition during 
analysis of argument values, no explicit error is reported, 
Instead, the result is an integer scalar indicating the 
types of error. Note that the function is not changed. The 
error types are 


1 - WS FULL; the function definition requires more 
workspace storage than is available 


2 - DEFN ERROR; causes are 
* the argument is ill-formed 
e inname is not the name of a function 


* fnname is the name of a locked, executing, 
suspended, pendent, or waiting function 


* an attempt was made to delete line 0 of fnname 


* the first nonblank character in line is not a 
left bracket 


* n is negative or greater than 9999.9999. o 


3 - (reserved) 
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4 - SYMBOL TABLE FULL; the function definition would 
exceed the number of symbols available in the 
symbol table. 


5 - UNMATCHED QUOTES; the argument contains an odd 
number of quotes outside comments. 


6 - (reserved) 
7 - (reserved) 
8 - (reserved) 


9 - LIMIT ERROR; the argument contains the character 
representation of a number whose absolute value 
exceeds 1.797693134862316E308. 


An argument to [IDEFL may contain a function line that 
begins with a right parenthesis, or that contains a newline 
character, a del symbol (V), or del-tilde symbol (9) not in 
a comment or character constant. While such a line produces 
no error when used with JDEFL, it will result in a SYNTAX 
ERROR when the line is executed. 
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ZBL -- Delay Execution pL 


The monadic system function (DL delays execution of the 
statement in which it appears. 


Syntax 
result + IDL seconds 


result - the explicit result 
Seconds - the duration of the delay 


Argument 


The argument to DL is a numeric singleton. It 
determines the duration of the pause in seconds, and can be 
fractional. The delay can be aborted by a single BREAK 
signal, which also suspends the program using !IDL at the 
next interruptible point. 


Resu. 


The explicit result of (DZ is a numeric scalar whose 
value is the actual delay in seconds. If Break is signaled 
during execution of CDL, the value of the result may be less 
than the value of the argument. The value will not display 
when interrupted by a Break, but will be available if stored 
in a variable. 


Effect 


The function “DL delays execution of the statement in 
which it appears. 


The function GDL relies on the system clock maintained 
by DOS for its time measurement. DOS reports time rounded 
to the nearest centisecond, but the accuracy is limited by 
the frequency with which the clock changes value. Many 
personal computer systems have clocks that cannot measure 
time intervals shorter than 1/20 or 1/60 of a second because 
the clock does not "tick" (change value) more frequently. 
The clock in the IBM Personal Computer, and in others 
similar to it, ticks 18.2 times per second. Refer to your 
computer manufacturer's manual for a description of the 
precision of the system clock. Using the system clock, DL 
delays for a time as close as possible to the requested 
delay. However, the actual delay (that is reported as its 
result) may be slightly more than the requested delay. 


Example 
GDE 10 


10.05 (appears 10 seconds after pressing Enter 
on the line above) 
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Error Reports 


DOMAIN ERROR The argument has the proper rank but is 
not numeric valued, or it is negative. 

LENGTE ERROR The argument is not a singleton. 

WS FULL The explicit result requires more 


workspace storage than is available. 
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ZDM -- Diagnostic Message EDM 


The niladic system function DDM returns the last 
diagnostic message recorded in the workspace. 


Syntax 
result + JDM 
result - the explicit result 


Result 


The result of IDM is a character vector of the 
diagnostic message associated with the last error or 
interrupt that occurred in the workspace. An exception is 
an event that stops execution of an APL statement. 
Exceptions can be caused by error conditions (such as 
SYNTAX ERROR, RANK ERROR, LENGTE ERROR, or DOMAIN ERROR) or 
an attention interrupt (BREAK). 


UDM does not record the diagnostic message displayed 
when an error or attention occurs that does not signal an 
exception. JDM records the diagnostic message for all 
attentions and for those errors which signal exceptions (see 
"DELX -- Error Latent Expression"). 


The value returned by DDM is stored in the workspace 
and is saved when the workspace is saved. 


If there is not enough workspace storage available when 
an error or attention occurs, the system displays NO SPACE 
FOR TDM followed by the diagnostic message. (DM is empty 
after a NO SPACE FOR _DM error. 


System-produced diagnostic messages may be altered or 
extended in the future. Applications that analyze the 
result of [DM should, therefore, be designed to allow easy 
modification. One such technique is to use the same 
function for analyzing the diagnostic message throughout an 
application. 
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Examples 


)CLEAR 
CLEAR WS 

PIDM 
o 

344 
VALUE ERROR 

3*4 

^ 

eDDM o DDM 
31 
VALUE ERROR 

3*4 

SAVE TEMP 

)CLEAR 
CLEAR WS 

pDDM 
o 

)LOAD TEMP 


1 TEMP SAVED... 
M 
VALUE ERROR 


ara 
^ 


DELX + "* 
5*0 


at d 
23*9 1011 


CDM 
LENGTH ERROR 
23x 91011 


^ 
USLX + 'DERROR'' «+t 
23x 91011 


0ps 

DeLx + 'DpW' 

23 x 9 10 11 
LENGTE ERROR 


23x 91011 
^ 


Copyright 1983 STSC, Inc. 


(IDM is empty in à clear 
workspace. ) 


(An APL error is generated; the 
normal diagnostic message displays, 
since DELX«'[DM'.) 


(DDM now returns the diagnostic 
message associated vith the last 
error exception.) 


(The workspace is saved 
then cleared.) 


(CDM is empty.) 


(CDM was saved with the workspace.) 


(Note the undesirable result of an 
empty JELY. 

No output of computation result or 
error message.) 


(Error message is in DDM.) 


(Result is even less revealing.) 
(Same statement with same LENGTH 
ERROR is displayed.) 

(Empty line displays.) 


(ODM contains a single space.) 


(After experimenting, be sure to 
reset DELY.) 


3-52 System Functions 


Error Report 


WS FULL The explicit result requires more 
workspace storage than is available. 


Copyright 1983 STSC, Inc. 3-53 System Functions 


IDR 


RI ion DDR 


The system function DDR, in its monadic form, reports 
the datatype of its argument, or, in its dyadic form, yields 
a copy of its right argument converted to the datatype 
specified by its left argument. []DR, as described here, is 
specific to the APL*PLUS/PC System; it may be different or 
absent in other APL«PLUS Systems. 


Synta: 


result +- DDR data 
result + datatypespec [DR data 


result 7 the explicit result 
data - any APL array 


datatypespec - a integer singleton representing the 
desired data representation of the 
explicit result 


Argument 


The optional left argument to QDR is a new datatype to 
be imposed on the value of the right argument. It must be 
an integer singleton representing a datatype recognized 
within the APL*PLUS/PC System. 


The following datatypespec codes are used in the 
APL*PLUS/PC System: 


82 - 8-bit character 

163 - 16-bit integer 

645 - 64-bit floating-point data, formatted and 
normalized according to the IEEE standard. 


NOTE: More datatype codes may be added in later 
releases of the APL*PLUS/PC System. 


The last digit of the code represents the datatype: 1 for 
Boolean, 2 for character, 3 for integer, 4 and above for 
various forms of floating-point data (5 is the system's 
internal form of floating-point data; that is, the IEEE 
form). The preceding digits of the code represent the 
number of bits per element. 


The right argument to [DR is an APL array whose 
datatype is to be reported or converted. 


Result 
If the monadic form of [ÐR was used, the explicit 


result is a scalar integer representing the datatype of the 
right argument. 
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If dyadic DDR was used, the explicit result is the 
value of the right argument converted to the datatype 
specified by the left argument. The [ISIZE and the internal 
representation of the data portion of the result are alvays 
the same as those of the right argument. The last element 
of the shape of the result vill reflect the change in 
datatype. 


The dyadic form of [DR is useful for transmitting 
floating-point numbers to an identical personal computer 
without loss of precision. Use DR to convert 
floating-point numbers to character data, transmit the 
character data, and convert it back to floating-point 
numbers when transmission is complete. This avoids the loss 
of precision encountered in source-level transfer. Since 
DDR converts floating-point numbers to character data, you 
can store this character representation of the data on any 
Computer, regardless of the method that system uses for 
internal representation of floating-point numbers. 


Effect 


The effect of monadic [DR is to return an explicit 
result reporting the datatype of the current internal 
representation of its argument. 


The effect of dyadic IDR is to return an explicit 
result. The explicit result is the value of the right 
argument re-interpreted as the specified datatype. This may 
result in an adjustment to the last element of the shape. 


NOTE: Not all eight-byte groups of random data 
correspond to valid normalized IEEE floating-point numbers 
(as used in the APL*PLUS/PC System). Using [DR to create 
such data within the system may lead to undefined results, 
Por example, the 645 “DR 4p 1 will be less than the smallest 
valid number in the system ([/10). 


Examples 
DDR 1.2 o DDR 'WORD' © ODR 110 


645 
82 
163 
£(B82:DDR NO/'N-TABLELOOKUP N* o OFREAD TN,N 
CHARS-'ABCDEFBIJKL"' 
pCHARS 
24 
INTEGER-163 QDR CHARS 
eINTEGER 
12 
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INTEGER 
8257 8258 8259 8260 8261 8262 8263 8264 B265 8266 8267 8268 
pMIXED-INTEGER,i10 a CATENATES CHARS WITH NUMBERS 
22 
FLOAT-&u5 [IDR CHARS 
pFLOAT 
3 
FLOAT 
3.00213493E 153 3.598811293E 153 4,195487656E 153 
82 (IDR FLOAT 
ABCDEFGHIJKL 


Error Reports 


DOMAIN ERROR The left argument contains an integer 
not representing a valid datatype in 
this system, or is non-integral or 
character-valued. 


LENGTH ERROR The left argument is a non-singleton. 
Or, the right argument does not 
provide enough data to fill an 
integral number of elements of the 
new datatype. 


RANK ERROR A non-singleton left argument has a 
rank greater than 2. 

WS FULL There is insufficient space in the 
active workspace for the explicit 
result. 
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Activate Full-Screen Editor vith Selected DEDIT 


The monadic system function DEDIT activates the 
full-screen editor for changes to the object named in its 
argument. DEDIT, as described here, is specific to the 
APL*PLUS/PC System; it may be different or absent in other 
APL*PLUS Systems. 


Syntax 
JEDIT object 


object - a character vector containing the name of the 
object to be edited 


Argument 


The argument to GEDIT is a character vector containing 
the name of the function or variable whose contents are to 
be displayed and possibly altered using the full-screen 
editor. If the argument is empty, the editor resumes the 
edit session last exited using Ctrl X, if possible. 


Result 


The system function JEDIT does not return an explicit 
result. 


Effect 


The effect of [EDIT is to store and clear the screen, 
display the object selected, and engage in interactive 
editing of the object with the user at the keyboard. 


ZEDIT uses the same full-screen editor that is called 
by )EDIT. The editing operations are described in "The 
Full-Screen Editor" in the Programmer's Manual. 


Upon exit from the full-screen editor, the screen and 
the cursor position are restored to their condition when the 
editor was invoked. ‘JEDIT removes [TRACE and 2STOP settings 
on a function. 


WARNING: If a WS FULL occurs during the editing 
session, or on exit with Ctrl E, you will lose the changes 
made during the editing session since there is not enough 
space available to store the result of these changes. You 
should, therefore, avoid lengthy editing sessions unless you 
save the results (with Ctrl S) from time to time. 
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Examples 
DEDIT 'CUSTOMERLIST" 


DEDIT 'PROGRAM' 
e QEDIT '"U 


Error Reports 

DOMAIN ERROR The argument contains an 
ill-formed name, numeric data, or 
the name of a variable whose 
contents are numeric. 

EDIT SESSION PENDING There is an edit session 


currently pending (suspended 
using Ctrl X). The last session 
must be cleared before starting a 
nev one. 


LIMIT ERROR (OBJECT EXCEEDS 65536 BYTES) 
The editor's internal form of the 
object would be too large to 
permit this object to be edited. 


NO EDIT SESSION PENDING ^ There is no edit session 
currently pending. You must 


Specify the name of the object to 
edit. 

NONCE ERROR The full-screen editor cannot be 
used under session startup option 
B=1. 


RANK ERROR The argument is not a vector or a 
matrix, 


SYMBOL TABLE FULL There is not room in the symbol 
table for the additional name, 


WS FULL Storing the result of the editing 
session requires more workspace 
storage than is available. 
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DELY -- Error Latent Expression TELY 


The workspace-related system variable [ZLY holds a 
representation of the APL expression to be executed in the 
event of an error exception. 


Domain 


The domain for assignment to [ELX is a character 
singleton or vector. 


Value when Referenced 


When CELX is referenced, its value is a character 
vector. 


Default Value in a Clear Workspace 


In a clear workspace, the default value of DELY is 
"Dna. 


DELK-Dependent Primitive Functions 
No primitive functions depend upon the value of LELY. 


Effect 


Whenever a trapped error occurs during execution of an 
APL expression or function, the statement *[ELY is executed. 
The most local value of CELX is referenced. Thus, if JELY 
has its default value ('LDM') when an error occurs, the 
system simply displays the error message (see "DM ~- 
Diagnostic Message"). 


If an error occurs during execution of the actual 
statement in -ELX, the system displays the diagnostic 
message and requests immediate execution input. If, 
however, the error handler calls a function, errors signaled 
within that function can be handled. 


1f an error occurs while the system is evaluating | 
input, the diagnostic message associated vith the error is 
displayed and the user is prompted again for input; ODM is 
not changed. Note that if a function call is entered in ae 
input, errors occurring within the called function are 
handled by (ELX. 


APL Errors Handled by [ELX 
The folloving errors are trapped (invoke the execution 


of JELX). Any error exceptions signaled by “ERROR are also 
trapped. 
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AXIS ERROR 


DIRECTORY FULL -- except when caused by a system 
command 

DISK ERROR -- except when caused by a system command 

DISK FULL -- except when caused by a system command 

DISK WRITE PROTECTED -- except when caused by a system 
command 


DOS COMMAND FILE NOT FOUND -- except when caused by a 
System command 

DOMAIN ERROR -- except when caused by a system command 

DRIVE NOT READY -- except when caused by a system 
command 

FILE ACCESS ERROR 

FILE ARGUMENT ERROR 

FILE DAMAGED 

FILE FULL 

FILE INDEX ERROR 

FILE NAME ERROR 

FILE NOT FOUND 

FILE SIZE ERROR 

FILE TIE ERROR 

FILE TIE QUOTA EXCEEDED 

FILE TIED -- except when caused by a system command 

FORMAT ERROR -- generated by SFMT 

INDEX ERROR 

INSUFFICIENT HANDLES 

INVALID WS NAME -- except when caused by a system 


command 
LENGTH ERROR -- except when caused by a system command 
e (for example, )CMD followed by more than 123 
characters) 
LIBRARY NOT FOUND -- except when caused by a system 
command 


LIMIT ERROR -- except when caused by a system command 

NONCE ERROR -- except when caused by a system command 

NOT YOUR WS -- except when caused by a system command 

RANK ERROR -- except when caused by a system command 

STACK FULL 

SYNTAX ERROR 

VALUE ERROR 

WS FULL -- except when caused by a system command 

WS NOT COMPATIBLE -- except when caused by a system 
command 

WS NOT FOUND -- except when caused by a system command 

WS T00 BIG -- except when caused by a system command 


Additional errors may be defined or added to the class 
of trapped errors in future releases of this system. 


Errors that are not trapped are 


* Input errors (including errors in expressions 
evaluated for {| input). 


o * Errors resulting from system commands. 
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e Errors signaled by an ill-formed statement in DELE. 


* WS FULL, SYMBOL TABLE FULL, or LIMIT ERROR errors 


signaled by the systen's inabili 
Statement into internal form. 


Examples 


v SAMPLEiOELY 
[13  DELYe' «ERR * 


Y SAMPLE2;JELY _ 
[1]  DELX-'JERROR ( 1*LDMiCTCNL) *DDM* 


Error Reports 


ty to translate a 


(In the function SAMPLE, 
DELX is used to branch 
to the error-processing 
part of the function if 
an error occurs.) 


(The function SAMPLE2 
uses LELX to invoke an 
error in the function 
that called SAMPLE2 (see 
"TERROR Signaling an 
Error Exception").) 


During Execution Any APL execution error can occur during 


the execution of DELI. 


character-valued or contains unmatched 


DOMAIN ERROR The value being assigned is not 
quotes. 
LIMIT ERROR The argument contains 


the character 


representation of a number whose absolute 


value is greater than 
1.797693134862316£308. 


RANK ERROR The value being assigned to DELX is not a 


singleton or a vector. 
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System Functions 


ERASE -- Erase Objects DERASE 


The monadic system function [ERASE erases, if possible, 
the most local definitions of a list of identifiers (names) 
in the active workspace. 


Syntax 
result + OERASE iglist 


result - the explicit result 
idlist - a list of identifiers 


Argument 


The argument contains a list of zero or more 
identifiers, It can be represented in several ways: 


* a character scalar, vector, or matrix containing one 
identifier 


* 8 character vector containing two or more 


identifiers, with each pair separated by one or more 
blanks 


e a Character matrix with one identifier in each rov. 
Result 


The explicit result of LERÁASE is a character matrix 
with each row containing an identifier whose definition vas 
not erased. Identifiers that were undefined before the 
execution of GERASE are not included in the result. 


If. the definitions of all specified identifiers are 
erased, the result is an empty matrix with shape 0 0. 


Effect 


Since the definitions of identifiers in the active 
workspace are erased if possible, the available work area 
may increase in size. OERASE does not erase the definitions 
of identifiers representing labels, system functions, system 
variables, or executing, suspended, pendent, or waiting 
functions. 


If DERASE produces a WS FULL or DOMAIN ERROR, none of 
the identifiers named in the argument have been erased. 


Exampie 
eL+LDERASE 'MYPROGRAM" 
POVR 'MYPROGRAM* 
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Error Reports 


DOMAIN ERROR The argument has the proper rank 
but is not character-valued, or it 
contains invalid identifiers. 


RANK ERROR The argument is not à matrix, o 
vector, or singleton. 


WS FULL The explicit result requires more 
workspace storage than is 
available. 

c A £ DERASE vith D 


(ERASE and CEX provide similar capabilities. but DERASE 
returns the identifiers that cannot be erased; QEY returns a 
Boolean vector indicating which identifiers were erased. 
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JERROR -- Signaling en Error Exception DERROR 


The monadic system function [ERROR signals an error 
exception. 


Syntax 
TERROR message 
Message - a character singleton or vector to be used as 
the first line of the diagnostic message 
associated with the resulting error exception 


Argument 


The argument to “ERROR is a character singleton or 
vector. It is recorded as the first line of the diagnostic 
message associated with the resulting error exception. 


If the argument to RROR is empty (''), no exception 
is signaled. This permits conditional signaling of error 
exceptions with a statement of the form “ERROR condition/ 
message. 


Result 

The function “ERROR does not return an explicit result. 
Effect 

LZERROR provides two facilities to the programmer: 


© the ability of a function to signal an exception to 
the program from which it was called 


* the ability to signal user-defined error exceptions. 


When TERROR is executed, the state indicator stack is 
stripped back to the environment from which the function 
executing TERROR was called. Then an error exception is 
signaled and the argument to (ERROR is recorded. If the 
State indicator is empty or contains only one function when 
DERROR is executed, the error exception is signaled in the 
global environment. 
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Examples 


In the function SQRT below, (ERROR is used to signal an 
error in the environment from which $QR7T is called instead 
of within SQRT itself. 


Y R-SQRT A; ELX 
[1]  LELY-'QERROR (UCDMVCTCNLO)-CIO)*CDM* 
[2]  Re4*0.5 

Y 


SQRT “1 
DOMAIN ERROR 
SQRT 7i 


In the next example, SQRT is modified to detect a 
negative argument and generate an error message that is more 
informative than the DOMAIN ERROR report normally produced 
by the system. 


Y R-SQRT Ai ELX 
Uu ZELY-'"ERROR ((LDMi TCNL)- 10) t DM* 
i2] ERROR (v/,A«0)/' ARGUMENT NEGATIVE" 
I3] 


ReAw0.5 
T 
SQRT “1 
ARGUMENT NEGATIVE 
SQRT 1i 
SQRT "A" 
DOMAIN ERROR 
SORT '4* 


If SQRT is called from another function and a negative 
argument is supplied to SQRT, an error is signaled in the 
calling function. 


V RM RELMASS ¥3C 
[11 COMPUTES RELATIVISTIC MASS OF A MOVING OBJECT 
[2] a M ++ REST MASS; V += VELOCITY 
[3] a C ++ SPEED OF LIGHT IN M/SEC 
[4]  C-300000000 
[5] ReM#SQRT 1-(/92)41C92 


1 RELMASS 2.9E8 
3.905667329 


1 RELMASS 3.5E8 a USING A VELOCITY > SPEED OF LIGHT 
ARGUMENT NEGATIVE 
RELMASS[S] ReMtSQRT 1-(Y*2)4C*2 
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The following technique can be used to clear the result 
of DDM, provided the state indicator is clear and (FLY does 
not call DERROR. 


DERROR * * 
PO-ODM 

1 

Error Reports 

DOMAIN ERROR The argument to [ERROR is of proper rank 
but is not character-valued. 

RANK ERROR The argument to [ERROR is not a singleton 
or a vector. 

WS FULL There is not enough space in the workspace 


to record the diagnostic message. 
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EX Erase Objects Der 
The monadic system function [DEY erases, if possible, 


the most local definitions of a list of identifiers (names) 
in the active workspace. 


Syntax 
result + DEY idlist 


result - the explicit result 
idlist - a list of identifiers 


Argument 


The argument contains a list of zero or more 
identifiers. It can be represented as one of the following: 


e a character scalar or vector containing one 
identifier 


e a character vector containing two or more 
identifiers, vith each pair separated by one or more 
blanks 

e a character matrix with one identifier in each row. 

Result 


The explicit result of [EX is a numeric vector, with 
one element for each identifier in the argument. 


Each element of the result is one of the following 
values: 


* 1 if the identifier was erased or undefined 
* 0 if the identifier was not erased 


* 0 if the corresponding identifier of the argument is 
iil-forned. 


Effect 


Since the definitions of identifiers in the active 
workspace are erased if possible, the work area available 
may increase. [EY does not erase an identifier if it is a 
label, a system function, a system variable, or an 
executing, pendent, suspended, or waiting function. 


If (EX produces a WS FULL or DOMAIN ERROR, nothing has 
been erased. 
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Example 


DEX 'TRI' 
1 
oDYR 'TRI' 
o 
Error Reports 
DOMAIN ERROR The argument has the proper rank but is 
not character-valued. 
RANK ERROR The argument is not a matrix, vector, or 
Singleton. 
WS FULL The explicit result requires more 


workspace storage than is available. 
Comparison of [EX with (ERASE 


[EX and ERASE provide similar capabilities. They are 
compared under "[ERASE -- Erase Objects". 
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JFAPPEND File Append DF APPEND 


The dyadic system function [F4PPEND appends a value to 
the end of a designated file. It creates a new component in 
the file, with a value identical to that of the left 
argument and a component number one more than the largest 
Previous component number. 


Synta: 
result + value OFAPPEND tieno 
result + value []PAPPEND tieng passno 

value - any APL array 


tieno - a positive integer file tie number 


passno an integer passnumber 
result the explicit result 
Arguments 


The left argument is the value to be appended to the 
file. It can be of any rank, shape, or data type. 


The right argument designates the file (by file tie 
number) and passnumber. If the passnumber is omitted, it ís 


assumed to be zero. The right argument must be an 
integer-valued singleton or two-element vector. 


Result 


The explicit result of [FAPPEND is the number of the 
new component. 


Effect 


A new data component is appended to a file, along with 
component information (ÜFADCI). 


For files vith no limit on their growth (a file 
reservation of 0), [FAPPEND may increase the amount of disk 
storage occupied by the file. 


Access 


The file must be tied, the passnumber must match the 
one in effect, and the user must have append access. 


The access code for DFAPPEND is 8. 
Examples 
COMP-(DVR 'TRI') DFAPPEND 27 


LIBRARY []FAPPEND 33 31101 
21 
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Error Reports 
DISK ERROR 


DISK FULL 


DISK VRITE 
PROTECTED 


DOMAIN ERROR 


DRIVE NOT READY 


FILE ACCESS ERROR 


FILE DAMAGED 


FILE FULL 


FILE INDEX ERROR 


FILE TIE ERROR 


LENGTH ERROR 


RANK ERROR 


WS FULL 


A disk error has occurred. probably due 
to a hardware fault or to an unformatted 
or defective disk. 


The operation cannot be done in the 
storage available in the specified 
library. Use []FDUP, [(]FERASE, (WERASE, or 
)DROP to eliminate unneeded storage and 
try again. 


The disk now in the disk drive has a 
protective cover over its notch 
preventing any alteration of its 
contents. 


The right argument has the proper rank 
and length, but is not integer-valued or 
exceeds 32,767. Or, the tie number is a 
zero or a negative value. 


An attempt has been made to use an empty, 
open. or non-existent disk drive. 


The user is not permitted to append to 
this file, or the passnumber is 
incorrect. 


Invalid values have been found in the 
file component directory, possibly from 
having removed the disk while the file 
was tied. 


The space required for the new component 
would cause the file to exceed its file 
reservation. 


The new component number would have been 
32767. 


The file tie number is not tied to a 
file. 


The right argument has the proper rank, 
but does not have exactly one or two 
elements. 


The right argument is not a vector or 
Singleton. 


The explicit result requires more space 
than is available in the active 
workspace. 
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IFAVAT£ -- Fil em Availabi DFAVAIL 


The system constant OFAVAIL indicates if the 
APL*PLUS/PC Shared File System is currently available for 
use. ([JFAVAIL exists in the APL«PLUS/PC System primarily for 
compatibility with other APL*PLUS Systems, where it 
indicates whether or not the file system is available. 


Syntax 
result + DFAVAIL 
result - the explicit result 
Resvit 


The explicit result of ÜFAVAIL is always 1 in the 
APL*PLUS/PC System, 


Effect 
Since the result of DFAY4IL in this system matches its 

behavior on other APL*PLUS Systems, programs from such 

systems which test for availability before proceeding will 

run smoothly on the APL*PLUS/PC System, 

Access 


No special access code is required for DFAVAIL. 


Exror_Report 

WS FULL Displaying the referenced value would 
require more workspace storage than is 
available. 
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DFCREATE -- File Create DFCREATE 
The dyadic system function [FCREATE creates a new APL 
component file. It establishes a new name, ties the file, 
and reserves disk space in the requested amount (if any). 
Syntax 
'fileid size' DFCREATE tieno 


fileid - a character vector containing a file name, 
optionally preceded by a library number 


size - optional file size limit in bytes 
tieno - a positive integer file tie number 
Arguments 


The left argument designates the file identification 
and an optional size limit of the file. The left argument 
must be a character vector or singleton, containing only 
digits, letters 4 through Z, and spaces. If the library 
number is omitted, the current default library is assumed. 
The file name must begin with a letter, and can be followed 
by up to seven additional letters or digits. 


The optional size limit designates an amount of file 
storage to be immediately reserved (allocated) on the disk 
and not to be exceeded by file growth. Since DOS disk 
storage is allocated in multiples of 512 bytes, a file 
reservation which is an exact multiple of 512 wastes no 
bytes on the disk. A newly created file in the APL*PLUS/PC 
System always has a default file reservation of zero, if no 
other reservation is specified, meaning that the file has a 
Single block of disk space reserved for it and no growth 
limit imposed upon it. Disk space is added as needed; the 
default size of additional blocks of disk space is 4,096 
bytes. The default size of additional blocks of disk space 
can be changed to other multiples of 512 bytes using [IPOKE. 


The right argument designates an available file tie 
number. It must be a positive integer-valued singleton, 
The user must have no other file currently tied with this 
number. 


Result 


The function []FCREATE does not return an explicit 
result. 


Effect 


A new file is created and tied and flagged as belonging 
to the user account number that created it. If a file 
reservation (gize) has been specified, that amount of disk 
space is immediately reserved. Otherwise, one block of 
space is reserved. 
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Access 


No access code is required for [FCREATE. 


Examples 


'TEXTFILE' LFCREATE 27 


‘PRINTOUT 80000" 


Error.Repor 


DIRECTORY FULL 


DISK ERROR 


DISK FULL 


DISK WRITE 
PROTECTED 


DOMAIN ERROR 


DRIVE NOT READY 


FILE ARGUMENT ERROR 


FILE NAME ERROR 


FILE SIZE ERROR 


FILE TIE QUOTA 
EXCEEDED 
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DFCREATE 33 


There is no space for additional 
names in the directory of this disk 
without first dropping workspaces or 
erasing files. 


A disk error has occurred, probably 
due to a hardware fault or to an 
unformatted or defective disk. 


The operation cannot be done in the 
available system storage. Use 
OFERASE, DFDUP, DNERASE, or )DROP to 
eliminate unneeded storage and try 
again. 


The disk now in the disk drive has a 
protective cover over its notch 
preventing any alteration of its 
contents. 


The right argument has the proper 
rank and length, but is not 
integer-valued, exceeds 32,267, or 
Contains à zero or a negative 
number, 


An attempt has been made to use an 
empty, open, or non-existent disk 
drive. 


The left argunent is ill-formed, 
numeric, or not a vector or 
singleton. 


A file with the same file 
identification already exists in 
that library. 


An attempt has been made to specify 
a file reservation (size limit) that 
is out of range. 


Performing the operation would have 
caused the user to have more than 
the maximum number of files (twenty) 
tied at once. 


System Functions 


INSUFFICIENT HANDLES 


LENGTH ERROR 


LIBRARY NOT FOUND 


RANK ERROR 
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The maximum number of files that DOS 
allows open at one time would be 
exceeded. If you can untie a file, 
you can free a handle for the 
attempted operation. To increase 
the number of handles available, 
include FILES=n (where n is 5 more 
than the desired file tie quota) in 
your CONFIG.SYS file and reboot the 
system. For the default file tie 
quota of 10, use FILES=15. 


The right argument has the proper 
rank. but does not have exactly one 
element. 


The APL library (DOS directory) you 
are trying to use cannot be found on 
the disk in the disk drive indicated 
by (1178S. Failure to find the 
library may result from not 
including a space between the 
library number and file name. 


The right argument is not a vector 
or singleton. 
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DEDROP -- File Drop of Components ÜFDROP 


The monadic system function JFDROP drops components 
from either end of a file. It does not change the numbers 
of remaining components. 


Syntax 


JFDROP 
JFDROP tieno n pessno 


tieno 


n 


a positive integer file tie number 

an integer designating the number and location 
of components to be dropped 

passno - an integer passnumber 


Argument 


The argument designates the file (by file tie number), 
the components to drop, and the passnumber. The absolute 
value of n is the number of components to be dropped from 
the low-numbered end of the file if n is positive, or from 
the high-numbered end of the file if n is negative. If n is 
zero, no components are dropped. If the passnumber is 
omitted, it is assumed to be zero. The argument must be an 
integer-valued, two- or three-element vector. 


Result 
The function (JFDROP does not return an explicit result. 
Effect 


Components are dropped from a file. This means that 
the data is no longer accessible using [FREAD or [IFRDCI, nor 
can new data be stored there by LFREPLACE. Dropping 
components from the file does not free physical storage 
space for immediate re-use. Space from components dropped 
at the end of the file can only be re-used for appending to 
the file from which they were dropped. unless the file is 
resized down or compacted. CFDUP can reclaim the wasted 
space. 


Access 


The file must be tied, the passnumber must match the 
one in effect, and the user must have drop access. 


The access code for DFDROP is 32. 
Example 

DFSIZE 27 
1 10 7424 100000 

DFDROP 27 2 


DFSIZE 27 
3 10 7424 100000 
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Error Reports 
DISK ERROR 


DISK WRITE 
PROTECTED 


DOMAIN ERROR 


DRIVE NOT READY 


FILE ACCESS ERROR 


FILE DAMAGED 


FILE INDEX ERROR 


FILE TIE ERROR 


LENGTH ERROR 


RANK ERROR 


A disk error has occurred, probably due 
to a hardware fault or to an unformatted 
or defective disk. 


The disk now in the disk drive has a 
protective cover over its notch 
preventing any alteration of its 
Contents. 


The argument has the proper rank and 
length, but is not integer-valued or 
exceeds 32767. Or, the tie number is a 
zero or a negative number. 


An attempt has been made to use an empty, 
open, or non-existent disk drive. 


The user is not permitted to drop 
components from this file, or the 
passnumber is incorrect. 


Invalid values have been found in the 
file component directory, possibly from 
having removed the disk vhile the file 
was tied. 


The number of components to be dropped 
exceeds the number of components in the 
file. 


The referenced file tie number is not 
tied to a file. 


The argument has the proper rank, but 
does not have exactly two or three 
elements. 


The argument is not a vector or 
singleton. 
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DEDUP -- Duplicate File DrpuP 


The dyadic system function DFDUP creates an exact copy 
Of the data, access matrix, component information, and 
reservation (size limit) of a file in a new, compact file 
with a new name, The user who duplicates the file becomes 
the file owner. [FDUP, as described here, is specific to 
the APL*PLUS/PC System; it may be different or absent in 
other APL*PLUS Systems. 


Syntax 


'fileid size' CFDUP tieno 
'fileid size' DFDUP tieno passno 


fileid - a character vector containing a file name, 
optionally preceded by a library number 

Size  - optional file reservation (size limit), in bytes 

tieno - a positive integer file tie number 

Passno - an integer passnumber 


Arguments 


The left argument must be a character vector or 
singleton, containing only digits, letters 4 through Z, and 
spaces, that designates the file identification for the new 
duplicate file. If no library number is given, the current 
default library is assumed. The file name must begin with a 
letter, and can include up to seven additional letters or 
digits, If the file name already exists in the designated 
"target" library, the system displays a FILE NAME ERROR. 


The optional size limit designates an amount of file 
storage to be immediately reserved (allocated) on the disk 
and not to be exceeded by file growth. A file reservation 
of zero means that the file has no disk space reserved for 
it beyond what it currently occupies and no growth limit 
imposed upon it. Disk space is added as needed. The 
default size of disk space additions is 4,096 bytes; the 
size can be changed to other multiples of 512 bytes using 
IPOKE. 


A file reservation other than zero must be no smaller 
than the current file data size (the third element of the 
result of []FSIZE). f no reservation is specified, the 
reservation of the file being duplicated with [JFDUP will be 
used. Since DOS disk storage is ,allocated in multiples of 
512 bytes, a file reservation whith is an exact multiple of 
512 wastes no bytes on the disk. 


The right argument must be an integer-valued singleton 
or two-element vector designating the file tie number and 
passnumber. If the passnumber is omitted, it is assumed to 
be zero. 
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Result 
The function CFDUP does not return an explicit result. 
Effect 


QFDUP creates a compacted copy of all the data in the 
file designated by the tieno under the new file 
identification fileid, and leaves the old file in place 
unless the new and old fileids are the same. The new file 
is owned by the user account number that created the 
duplicate. 


CFDUP does not change either “FNAMES or “lFNUMS, but if 
the new file name given is identical to the old file name, 
the old copy is replaced by the new (possibly more compact} 
file that is tied to that number. 


If the new and old files are not owned by the same user 
account number, the owner of the old file will have no 
access to the new file except that which is explicitly 
granted by the access matrix (which has also been 
duplicated). The result of ^FNAMES will not reflect the new 
file identification. since the new file has not been tied to 
a user-specified tie number. 


For maximum safety, the new file is first built under a 
temporary file name with the extension .T$F (temporary 
shared file). Only upon successful completion of the 
duae file is the old file erased and the temporary file 
renamed. 


The new file may occupy less space on disk than the 
original, since abandoned space resulting from a |FREPLACE 
of different sized data or from a i|lFDROP of low numbered 
components is eliminated. See “Freeing Disk Space by 
Compacting Files" in the Programmer's Manval. 


NOTE: Use of JFDUP is slow when compared to other file 
operations since it does the equivalent of a FREAD and a 
PAPPEND for every component in the file. Much of the need 
to use (FDUP can be eliminated by using a set of initial 
components that are as large as they might be likely to 
grow. Smaller components would be stored within the same 
space. 


Aci 


The file to be duplicated must be tied, the passnumber 
must match the one in effect. and the user must have 
duplicate access. The access code for  FDUP is 16384. 


Copyright 1983 STSC, Inc. 3-78 System Functions 


Example 
ÜFLIB 1 

1 LISTINGS 
LISTINGS’ 
OFWAMES 

1 LISTINGS 
" LEANINGS* 
JFNAMES 

1 LISTINGS 
DFLIB 1 

1 LISTINGS 

1 LEANINGS 


Error Reports 
DIRECTORY FULL 


DISK ERROR 


DISK FULL 


DISK WRITE 
PROTECTED 


DOMAIN ERROR 


DRIVE NOT READY 


FILE ACCESS ERROR 


FILE ARGUMENT ERROR 
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DFTIE 10 


Group 10 


There is no space for additional 
names in the directory of the target 
disk without first dropping 
workspaces or erasing files. 


A disk error has occurred, probably 
due to a hardware fault or to an 
unformatted or defective disk. 


The new file cannot be created in 
the storage available in the 
specified library. Use [FERASE, 
DNERASE, or )DROP to eliminate 
unneeded storage and try again, or 
duplicate the file in a library that 
has more space. 


The disk now in the target disk 
drive has a protective cover over 
its notch preventing any alteration 
of its contents. 


The right argument has the proper 
rank and length, but is not an 
integer between 1 and 32,767 
inclusive. 


An attempt has been made to use an 
empty, open, or non-existent disk 
drive. 


The user is not permitted to 
duplicate this file, or the 
passnumber is incorrect. 


The left argument is ill-formed, 
numeric, or not a vector or 
singleton. 
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FILE DAMAGED 


FILE NAME ERROR 


FILE SIZE ERROR 


FILE TIE ERROR 


INSUFFICIENT HANDLES 


LENGTH ERROR 


LIBRARY NOT FOUND 


RANK ERROR 


Invalid values have been found in 
the file component directory, 
possibly from having removed the 
disk from the disk drive while the 
file was tied. 


A file with the same file 
identification already exists in the 
designated library. 


An attempt has been made to specify 
& non-zero file reservation (size 
limit) that is out of range or less 
than the size of the data in the 
file ([PSI2£[3]). 


The file tie number is not tied to a 
file. 


The maximum number of files that DOS 
allows open at one time would be 
exceeded. If you can untie a file, 
you can free a handle for the 
attempted operation. To increase 
the number of handles available, 
include FILES=n (where n is 5 more 
than the desired file tie quota) in 
your CONFIG.SYS file and reboot the 
System. For the default file tie 
quota of 10, use FILES=15, 


The right argument has the proper 
rank, but does not have exactly one 
or two elements. 


The APL library (DOS directory) you 
are trying to use cannot be found on 
the disk in the disk drive indicated 
by DLIBS. Failure to find the 
library may result from not 
including a space between the 
library number and workspace name. 


The right argument is not a vector 
or singleton. 
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)RERASE. 


ile Er; DFERASE 


The dyadic system function [FERASE erases an entire 
file. The file must be tied. [FERASE drops all components 
of the file, unties the file, and deletes the file name from 
the library list. All of the data in the file is destroyed. 


Syntax 
'fileià' ÜFERÁASE t 
+ eid' [FERASE tieng passno 
fileid - a character vector or singleton containing a 
file name, optionally preceded by a library 
number 


tieno - a positive integer file tie number 
Passno - an integer passnumber 


Arguments 


The left and right arguments must designate the same 
file. 


The left argument is the file identification of the 
file. If the library number is omitted, the current default 
library is assumed. The left argument must be a character 
vector or singleton. 


The right argument designates the file (by file tie 
number) and the passnumber. If the passnumber is omitted, 
it is assumed to be zero. The right argument must be an 
integer-valued singleton or two-element vector. 


Result 


The function [JPERASE does not return an explicit 
result. 


Effect 


A file is untied and erased from the library. All of 
the data in the file is destroyed, 


Access 


The file must be tied, the passnumber must match the 
one in effect, and the user must have erase access. 


The access code for [FERASE is 4. 
Examples 
"TEXTFILE' [FTIE 27 
‘TEXTFILE' (\FERASE 27 


‘1 PRINTOUT’ OFTIZ 33 32511 
‘1 PRINTOUT' SFERASE 33 32511 
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Error Reports 
DISK ERROR 


DISK WRITE 
PROTECTED 


DOMAIN ERROR 


DRIVE NOT READY 


FILE ACCESS ERROR 


FILE ARGUMENT ERROR 


FILE NAME ERROR 


FILE TIE ERROR 


FILE TIED 


LENGTH ERROR 


LIBRARY NOT FOUND 


RANK ERROR 


A disk error has occurred, probably due 
to a hardware fauit or to an 
unformatted or defective disk. 


The disk now in the disk drive has a 
protective cover over its notch 
preventing any alteration of its 
contents. 


The right argument has the proper rank 
and length, but is not integer-valued 
or exceeds 32,767. Or, the tie number 
is a zero or a negative number. 


An attempt has been made to use an 
empty. open, or non-existent disk 
drive. 


The user is not permitted to erase this 
file, or the passnumber is incorrect. 


The left argument is ill-formed, 
numeric, or not a vector or singleton. 


The file named in the left argument is 
not currently tied with the tie number 
in the right argument. 


The file tie number is not tied to a 
file. 


You cannot erase a file while it is 
being used as an input source (DIN 
file), an output sink (DOUT file), or a 
capture sink (QCAP file Execute 
JIOSTATE. 


The right argument has the proper rank, 
but does not have exactly one or two 
elements. 


The APL library (DOS directory) you are 
trying to use Cannot be found on the 
disk in the disk drive indicated by 
LIBS. Failure to find the library may 
result from not including a space 
between the library number and 
workspace name. 


The right argument is not a vector or 
singleton. 


Copyright 1983 STSC, Inc. 3-82 System Functions 


]FSOLD File Hold DrFROLD 
The monadic system function [JFHOLD is ignored by the 
APL*PLUS/PC System. It is included for compatibility with 
other APL*PLUS Systems where it allows synchronization of 
file operations during simultaneous shared use. 
Syntax 
ÜFZOLD value 
value - any APL array 
Result 
The function JF#OLD does not return an explicit result. 
Effect 


The function DFEOLD has no effect in the APL*PLUS/PC 
System. 


Access 


No access code is required for |j]FHOLD on the . 
APL*PLUS/PC System. On other APL*PLUS Systems, the code is 
2048, 
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EI lnput Format Conversion DFI 

The monadic system function UFZ converts character 
strings to numeric values. With this function, you can 
convert character vectors that are images of numbers to 
their numeric form. Decimal points, E-formats, and negative 
signs (^) are all recognized by OFI. 


The validity of the result of DFI can be checked using 
DYZ on the input character vector. 


Syntax 
result - DFI data 
result - the explicit result 


data - character data 
Argument 
The argument is a singleton or vector of character 
data. 
Result 


The explicit result of [FI is a numeric vector formed 
by taking successive groups of nonblank characters from the 
argument and converting them to numbers. The conversion 
process uses the same rules as when numeric constants are 
entered from the keyboard in immediate execution mode or 
evaluated input mode. Any group of characters in the 
argument that does not represent a vell-formed number 
appears as a zero in the result. 


Examples 
A+'666 71.20 .1 318159875* 
. OFT 4 
566 71.2 0.1 3.14159 
DEI? 2 € 
2 
eürz' 2 * 
1 
eDrr 'o* 
o 
OFT ‘ANSWER: 666° 
0 666 
B+'ANSWER IS 666 LBS.‘ 
Orr 8 
0 0 666 0 
C+" .25 -6.25 8,9,10* 
Orr e 
0.25 0 0 
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As suggested by the last example, a ninus sign (-) 
cannot be used in place of a negative sign ( ) to negate a 
number; and commas and other symbols do not separate fields. 
An example of a technique for modifying such symbols to form 
a valid argument for OFZ is 


EXT+* 0123456789E,,-7" 

INT-' 012340562895. 7 «' 

DFI INT[EYTi' .25 -6,25 8,9.10'] 
0.25 76.25 8 9 10 


The expression [FI Ų can be used like quad (D) for 
accepting numeric input from the terminal. Unlike quad, 
however, [FI [| does not permit entry of APL expressions or 
system commands. Because of this, her © may be more 
suitable than quad for accepting input data in many 
applications. 


FI can also be used to convert character data that was 
transferred into the APL*PLUS/PC System from native DOS 
files by a remote CPU. Numeric data can be brought into the 
APL*PLUS/PC System represented as characters. It is 
converted into numbers using (FI. 


Error Reports 

DOMAIN ERROR The argument is not character-valued or 
contains unmatched quotes. 

RANK ERROR The argument is not a vector or singleton. 

WS FULL The explicit result requires more 


workspace storage than is available. 


Use of DEZ with DYI 


The expression (D77 data)/LFI data returns the values 
from well-formed fields in the character vector data and 
ignores the others. 


While OQF7 and GV7 can be used directly (as in 
"Examples", above), they are used to greater advantage 
within an APL function tailored to control keyboard input 
for an entire application. Such an APL function can be made 
responsible for converting minus signs and other symbols, 
validating input fields, and performing other checks. For 
example, the function INCON shown below takes as its 
argument the number of fields to be entered from the 
keyboard, and returns the values of the fields as a numeric 
vector, INCON accepts commas or blanks, and minus or 
negative signs. It prompts and checks for the correct 
number of input values. 
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V 2eINCON YiY;INT:;EY. 
[1]  EXT-' 0123556289E. 


[2]  INT-' 01234567898. 0s" 
[3] ERR+O 
[4] L1:Y-(ERR/'TRY AGAIN. '), ‘ENTER ',vX 
[5] Y." NUMBER', (321) VS: 
Y-INT[EXT27) o Z«CFI Y 


1 
1 ERRe-(X2pZ)V-^/.WI Y o +ERRpL1 
v 


Kel 
Cia = 
0172 -3 +4 5.5 -6.6 77.7E77 BE-88 "SE«908 
VALUE ERROR z 
C 01 2 -3+ 4 5.5 - 6.6 7.77E78 8 E- 88 ^9 +99 


C: 


INCON 10 
ENTER 10 NUMBERS: za 
O 172 73 +u S.5 -6.66 77.7E77 8E-BB SE+99 
0 17273 4 5.5 76.6 7.77E78 8E 88  SE99 


INCON 4 
ENTER 4 NUMBERS: 
111 22.22 .33 . #444 
TRY AGAIN. ENTER 4 NUMBERS: 


111 22.22 .333 „4444 
111 22.22 0.333 0.5444 i o 
Using a function like INCON for input throughout an 


application helps keep rules for data entry simple and 
uniform. 
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DFLIB -- File Library List DFLIB 


The monadic system function [LIB returns a character 
matrix listing all the files in the designated library, even 
if the user has no access to them. 


Syntax 
result + [FLIB lib 
result - the explicit result 


lib - a single digit designating a library or DOS 
directory 


Argument 


The argument designates the library vhose files are to 
be listed. It must be a a positive integer corresponding to 
one of the operating disk drives, or an empty vector (which 
indicates all active libraries at once). 


Result 


The explicit result of DFLIB is a 22-column character 
matrix which contains one file identification in each row. 
The columns in the result are defined as follows: 


Column 1-10 Library number, right-justified 
Colum 11 Space 
Columns 12-22 File name, left-justified 


The ordering of the rows (file identifications) is 
alphabetic. 


CAUTION: The number of columns in the result of DFLIB 
may increase in the future. 


NOTE: If you have programs that were written using an 
earlier version of the APL*PLUS/PC System {when the explicit 
result of [FLIB was 10-columns wide), these programs can be 
used without modification after using a []POKE. 


NOTE: )FLIB produces the same list of files, but 
listed in multiple columns to save lines on the screen. 


Access 


No special access code is required for QFLIB. 
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Examples 


OFLIB i 
1 PERSONS 
1 SALES 


CFLIB 0 
0 PRIMES 


DFLIB '" 
0 PRIMES 
1 PERSONS 
1 SALES 


pLIFLIB 10 


ports 


DISK ERROR A disk error has occurred, 


probably due to 


a hardware fault or to an unformatted or 


defective disk. 


DOMAIN ERROR The argument is not integer-velued. 
LENGTH ERROR The argument is not a singleton or vector. 
WS FULL The explicit result requires more 


workspace storage than is 
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available. 


System Functions 


DENT 


The dyadic system function [IFMT formats character and 
numeric data into a character array for displaying in a more 
readable tabular form or for further processing. JEM? 
applies a field-specifying format string to the data. (FMT 
and its usage is described in detail with many examples in 
(STSC, 1983). 


the Formatting User's G 


- the explicit result 


fo: iiri ng - a character vector of format phrases 
data - an APL array 
Arguments 


The right argument can contain any numeric or character 
scalar, vector, or matrix. It can also be any APL 
expression (except FMT) that yields such an array. 


The left argument (formatstring) is a character vector 
that contains combinations of editing and positioning format 
phrases separated by commas. These phrases control the 
editing and displaying of data in the right argument. 


Editing format phrases take the following forms: 


rmdw Character 
rmew.s Exponential 
rmofw.d Fixed point 
rmé«pattern» Pattern 
rmiw Integer 


Positioning and text format phrases, which do not edit 
data, have the following forms: 


Tp or T Absolute tab 
rXp Relative tab 
r«text» Text insertion 


The following parameters, which appear in the format 
phrases above, are required vith the phrases shown in 
parentheses: 


à Decimal position parameter (F) 

P Position parameter (7, X) 

& Significant digits parameter (E) 
w Field width parameter (A, E, F, 1) 
«pattern» Pattern text parameter (6) 
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Repetition factors and modifiers. which appear in the 
format phrases above, are optional: 


Repetition factor 
Modifiers 


Bn 


Any combination of the following modifiers can be used 
with the phrases shown in parentheses: 


B Blank if zero (F, I) 

g Comma insertion (F, I) 

Ki Scale argument by 10*i (E, F, G, I) 

p Left justify (F, I) 

M<text> Negative left decoration (F, 6, I) 

N<text> Negative right decoration (F, G, I) 

O<text> Format zeros as text (F, G, I) 

P«text^ Positive or zero left decoration (F, 
G, 1) 

Q<text> Positive or zero right decoration (F, 
G, 1) 

R<text> Background fill (4, E, F, G, I) 


S<symbolpairs> Symbol substitution (F, G, I) 
Z Zero fill (F, 1) 


The text in the decorations, background fill, symbol 
substitution, and text insertion can be delimited by any of 
the following pairs of symbols: 


<> 
e > 
zm 
TE 
TENET: 
A group of format phrases can be repeated by enclosing 


it in a pair of parentheses and preceding the left 
parenthesis with a repetition factor. 


Result 
The explicit result of [JFMT is a character matrix. 
Example 


'G«(999) 999-9999»' [FMT 3019845000 9993019849999 
(301) 984-5000 
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Error Reports 
DOMAIN ERROR 


XXX FORMAT ERROR 


RANK ERROR 


WS FULL 


The left argument contains numeric rather 
than character data. 


A format phrase is ill-formed. The 
incorrect format phrase (or the first 16 
characters, if it is longer) precedes the 
words FORMAT ERROR. Such errors include 
tabbing to the left beyond the left margin 
(column 1), a single field with a width 
greater than 255, nesting parentheses 
Geeper than eight levels, or mismatched 
parentheses, 


The left argument is not a vector or 
singleton, or the rank of any value in the 
right argument is greater than two. 


The explicit result requires more 
workspace storage than is available. 
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ENAMES File Identifications of Tied Files DFNAMES 


The niladic system function JFNAMES returns the file 
identifications of all currently tied APL*PLUS/PC System 
files (those with DOS extension .4$F). 


Syntax 
result + jFNAMES 
result - the explicit result 
Result 
The explicit result returned by JFNAMES is a 22-column 
character matrix containing one file identification in each 
row. The rovs of the result have the same ordering as the 
result of IFNUMS. 
The 22 columns are defined as follows: 
Column 1-10 Library number, right-justified 
Column 11 Space 
Columns 12-22 File name, left-justified 
NOTE: If you have programs that were written using an 
earlier version of APL*PLUS/PC System (when the 
explicit result of DFNAMES was 10-columns wide), 
these programs can be used without modification after 
using a DPOKE. 
Access 


No special access code is required for the use of 
UFNAMES. 


Example 
UiFNAMES 
1 PERSONS 
0 PRIMES 


Error Report 


WS FULL The explicit result requires more 
workspace storage than is available. 
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IENUMS -- File Numbers of Tied Files DFNUMS 
The niladic system function OFNUMS returns the file tie 
numbers of all currently tíed APL«PLUS/PC System files 
(those with DOS extension ASF). 
Syntax 
result + DFNUMS 
result - the explicit result 
Result 
The explicit result of [FNUMS is a numeric vector of 


file tie numbers. The result has the same ordering as the 
rows of the result of DFNAMES. 


No special access is required for ()FNUMS. 
Examples 


ÜFNUMS 
2? 33 37 


DFUNTIE ÜFNUMS 
pJFNUMS 


Error Report 


WS FULL The explicit result requires more 
workspace storage than is available. 
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[Ue T 


OFRDAC 
The monadic system function [FRDAC reads the access 

matrix of a file and returns the value of the matrix as the 

result. 

Syntax 


RDAC tieno 
RDAC tieno passno 


ris 


- a positive integer file tie number 


lt - the explicit result 
o 
no - an integer passnumber 


passno 
Argument 
The argument designates the file (by file tie number) 

and the passnumber. If the passnumber is omitted, it is 


assumed to be zero. The argument must be an integer-valued 
Singleton or two-element vector. 


Result 
The explicit result of [FRDAC is a three-column numeric 


matrix containing the access matrix of the file. The access 
matrix of a newly created file has no rows. 


Access 
The file must be tied, the passnumber must match the 
one in effect, and the user must have the authority to read 
the access matrix. 
The access code for [FRDAC is 4096. 
Examples 
pFRDAC 27 
CERDAC 33 7655 
12304 16059 7655 
23405 16063 o 
Error Reports 
DISK ERROR A disk error has occurred. probably due 
to a haróvare fault or to an unformatted 
or defective disk. 
DOMAIN ERROR The argument has the proper rank and 
length. but is not integer-valued or 


exceeds 32,767. Or, the tie number is 
zero or a negative number. 
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DRIVE NOT READY 


FILE ACCESS ERROR 


FILE DAMAGED 


FILE TIE ERROR 


LENGTE ERROR 


RANK ERROR 


WS FULL 


An attempt has been made to use an empty, 
open, or non-existent disk drive, 


The user is not permitted to read the 
access matrix for this file, or the 
passnumber is incorrect. 


Invalid values have been found in the 
file component directory, possibly from 
having removed the disk while the file 
was tied. 


The file tie number is not tied to a 
file. 


The argument has the proper rank, but 
does not have exactly one or two 
elements. 


The argument is not a vector or 
singleton. 


The explicit result requires more 
workspace storage than is available. 
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DFRDCI -- File Read of Component Information OFRDCI 


The monadic system function [JFRDCI returns a vector of 
information about a component of a file. 


Syntax 


result + JFRDCI tieno compno 
result + JFRDCI tieno compno passno 


result - the explicit result 

tieno a positive integer file tie number 

Compno - an integer designating the position of a 
component in a file 

passno - an integer passnumber 


Argument 


The argument designates the file (by file tie number), 
the component number, and the passnumber. If the passnumber 
is omitted. it is assumed to be zero. The argument must be 
an integer-valued, two- or three-element vector. 

Result 
The explicit result of CFRDCI is currently a 
three-element numeric vector containing the folloving 

information: 


[1] the workspace storage needed to hold the 
Component, in bytes 


[2] the account. number of the person who most recently 
executed [JFAPPEND or [JFREPLACE on the component 


[3] the time of the most recent execution of (iFAPPEND 
or Ü]FREPLACE on the component, in microseconds 
since 00:00 1 January 1900. This is consistent 
with other APL«PLUS Systems. These values are 
drawn from the system clock maintained by DOS, 
which reports them in centiseconds. The accuracy 
in the APL*PLUS/PC System is limited by the 
accuracy of the system clock. The clock in the 
IBM Personal Computer, and in others similar to 
it. ticks 18.2 times per second. 


Access 

The file must be tied, the passnumber must match the 
one in effect, and the user must have the authority to read 
component information. 


The access code for [FRDCI is 512. 
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Example 


)COPY O FILEAID TIME 


SAVED... 


TIME (DFRDCI 27 1)[3] 
9/08/85 18:56:08.570000 


ro r| 


DISK ERROR 


DOMAIN ERROR 


DRIVE NOT READY 


FILE ACCESS ERROR 


FILE DAMAGED 


FILE INDEX ERROR 


FILE TIE ERROR 


LENGTH ERROR 


RANK ERROR 


WS FULL 


A disk error has occurred, probably due 
to a hardware fault or to an unformatted 
or defective disk, 


The argument has the proper rank and 
length, but is not integer-valued or 
exceeds 32,767. Or, the tie number or 
component number is zero or a negative 
number, 


An attempt has been made to use an empty, 
open, or non-existent disk drive. 


The user is not permitted to read 
component information, or the passnumber 
is incorrect, 


Invalid values have been found in the 
file component directory, possibly from 
having removed the disk from the disk 
drive while the file was tied. 


The component number given lies outside 
the file component number limits. 


The file tie number is not tied to a 
file. 


The argument has the proper rank, but 
does not have exactly two or three 
elements, 


The argument is not a vector or 
singleton, 


The explicit result requires more 
workspace storage than is available. 
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le Read of Component FREAD 


The monadic function “FREAD reads a component of a file 
and returns its value as the result. 


Syntax 


result + LFREAD tieno compno 
result + LFREAD iieno compno passno 
result - the explicit result 
tieno - a positive integer file tie number 
compno - an integer designating the position of a 
component in a file 
passno - an integer passnumber 


Argument 
The argument designates the file (by file tie number), 
the component number, and the passnumber. If the passnumber 


is omitted, it is assumed to be zero, The argument must be 
an integer-valued, two- or three-element vector. 


Result 


The explicit result of “FREAD is the value of the APL 
array in the component of the file. 


Access 


The file must be tied, the passnumber must match the 
one in effect, and the user must have read access. 


The access code for “FREAD is 1. 


Effect 


A copy of the data in the specified component is 
brought into the workspace. 


Example 


QFREAD 27 1 
THIS FILE CONTAINS SUMMARY SALES DATA FOR 1982. CREATED 26 
JANUARY 1983. 


Error Reports 

DISK ERROR A disk error has occurred, probably due 
to a hardwere fault or to an unformatted 
or defective disk. 

DOMAIN ERROR The argument has the proper rank and 


length, but is not integer-valued or 
exceeds 32,767. Or, the tie number or 
component number is zero or a negative 
number. 
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DRIVE NOT READY 


FILE ACCESS ERROR 


FILE DAMAGED 


FILE DATA ERROR 


FILE INDEX ERROR 


FILE TIE ERROR 


LENGTH ERROR 


RANK ERROR 


WS FULL 


An attempt has been made to use an empty, 
open, or non-existent disk drive, 


The user is not permitted to read this 
file. or the passnumber is incorrect. 


Invalid values have been found in the 
file component directory, possibly from 
having replaced the disk while the file 
was tied. 


An attempt was made to read a file 
component that does not contain an APL 
value. The component was written by a 
non-APL program. 


The specified component number lies 
outside the file component number limits. 


The file tie number is not tied to a 
file. 


The argument has a rank less than 2, but 
does not have exactly two or three 
elements. 


The argument is not a vector or 
singleton. 


The explicit result requires more 
workspace storage than is available, 
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IFRENAME 


File Rename DFRENAME 


The dyadic system function (IFRENAME sets the file name 
of the fiie. The user who renames the file becomes the file 


owner. 


' DFRENAME tieno 
size’ CFRENAME tieno passno 


a character vector containing a file name, 
optionally preceded by a library number 
optional file size limit in bytes 

- a positive integer file tie number 

an integer passnumber 


The left argument must be a character vector or 
Singleton, containing only digits, letters 4 through Z, and 
spaces, designating the file identification and optional 
size limit of the file. The file name must begin with a 
letter, and can include up to seven additional letters or 
digits. If the library number is omitted, the default 
library is assumed. 


The right argument must be an integer-valued singleton 
or two-element vector designating the file tie number and 
passnumber. If the passnumber is omitted, it is assumed to 
be zero. 


The optional size limit designates the amount of disk 
storage to be reserved immediately for the file, and beyond 
which it cannot grov. 


Result 


The function [FRENAME does not return an explicit 
result. 


Effect 


OFRENAME resets the file owner to the user account 
number from which the operation is performed, resets the 
file name to the one specified in the left argument, and, if 
the left argument specifies a reservation (size), resets the 
amount of space reserved on the disk. 


If the file name already exists in the library or if a 
different library is specified (even by default), the system 
signals a FILE NAME ERROR. 


1f ownership of the file is changed, the former owner 
will lose all access to the file except that which is 
explicitly granted by the access matrix. The result of 
DENAMES will reflect the new file identification. 
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Access 


The file must be tied, the passnumber must match the 
one in effect, and the user must have rename access. The 
access code for []PRENAME is 128. 


Examples 


ÜFLIB 0 

0 LISTINGS 
'LISTINGS' DFTIE 10 
'LEANINGS' QFRENAME 10 
DFLIB 0 

0 LEANINGS 


Error Reports 


DIRECTORY FULL There is no space for additional 
names in the directory of this disk 
without first dropping workspaces or 
erasing files. 


DISK ERROR A disk error has occurred, probably 
due to a hardware fault or to an 
unformatted or defective disk. 


DISK WRITE The disk now in the disk drive has a 

PROTECTED protective cover over its notch 
preventing any alteration of its 
Contents. 

DOMAIN ERROR The right argument has the proper 


rànk and length, but is not 
integer-valued or exceeds 32,767. 
Or, the tie number is zero or 
negative. 


DRIVE NOT READY An attempt has been made to use an 
empty, open. or non-existent disk 
drive. 


FILE ACCESS ERROR The user is not permitted to rename 
this file, or the passnumber is 
incorrect. 


FILE ARGUMENT ERROR The left argument is ill-formed, 
numeric, or not a vector or 
singleton. 


FILE DAMAGED Invalid values have been found in 
the file component directory, 
possibly from having removed the 
disk while the file was tied. 
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FILE NAME ERROR 


FILE SIZE ERROR 


FILE TIE ERROR 


LENGTH ERROR 


RANK ERROR 


A file vith the same file 
identification already exists in the 
designated library, or an attempt 
has been made to rename the file 
onto a different disk drive (use 
ÜFDUP instead). 


An attempt has been made to specify 
a file reservation (size limit) that 
is out of range or smaller than the 
present size of the file. 


The file tie number is not tied to a 
file. 


The right argument has the proper 
rank, but does not have exactly one 
or two elements. 


The right argument is not a vector 
or singleton. 
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IFREPLACE File Replace of Component OFREPLACE 


The dyadic system function [FREPLACE stores a value in 
an existing component of a file. 


Syntax 


value [FREPLACE tieng compno 
value ÜFREPLACE tieno compno passno 


value -~ any APL array 

tieng - a positive integer file tie number 

gompno - an integer designating the position of a 
component in a file 

Passno - an integer passnumber 


The left argument is the value to be stored in the 
file. It can have any rank, shape, or datatype. 


The right argument designates the file (by file tie 
number), the component number, and the passnumber. 1f the 
passnumber is omitted, it is assumed to be zero. The right 
argument must be an integer-valued, two- or three-element 
vector, 


Result 


The function [FREPLACE does not return an explicit 
result. 


Effect 


The value of the designated component of the file is 
Changed, along with the component information (CFRDCI). 


For files vith no limit on their growth (a file 
reservation of 0), OFREPLACE may increase the amount of disk 
storage occupied by the file. 


NOTE: Replacing a component of a file vith an empty 
vector vill not decrease the amount of storage needed. When 
the current array in a file component is replaced with an 
array larger than has been previously stored in this 
Component, additional disk space is used for the entire 
larger array. The space used for the previous largest array 
in this file component is not used again by this file 
although it remains allocated to this file. When the array 
in a file component is replaced with a smaller array, no new 
disk space is used, but some of the space already allocated 
for this component is not used. If the smaller array in 
this file component is replaced by a larger array up to the 
size of the largest array ever stored in this component, no 
nev disk space is used. 
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Thus, a file whose array components grow by numerous 
replacements vith slightly larger arrays can accumulate a 
lot of allocated disk space that is unusable. This 
abandoned space can be recovered by copying the file using 
FREAD and LFÁAPPEND, or by using [FDUP. You can avoid the 
burden of abandoned disk space by initially appending the 
components vith arrays that are as large as the arrays are 
likely to grow. Then replace the full-sized arrays with the 
small starting-size arrays. The disk space required will 
not increase as the arrays grow unless one of the arrays 
becomes larger than the initial array in its component. 


See also "Freeing Disk Space by Compacting Files" in 
the Programmer's Manual. 


Access 


The file must be tied, the passnumber must match the 
one in effect, and the user must have replace access. 


The access code for [|FREPLACE is 16. 
Example 


LIBRARY-DÜFREAD 33 10 
LIBRARY-LIBRARY,[1] CAID[1].CFSIZE 33)[2] 
LIBRARY GFREPLACE 33 10 


Error Reports 


DISK ERROR A disk error has occurred, probably due 
to a hardware fault or to an unformatted 
or defective disk. 


DISK FULL The operation cannot be done in the 
available space on this disk, Use 
LFERASE, DNERASE, GFDUP, or )DROP to 
eliminate unneeded storage and try again. 
Or use [FDUP to compact the file onto 
another disk, 


DISK WRITE The disk now in the disk drive has a 

PROTECTED protective cover over its notch 
preventing any alteration of its 
Contents. 

DOMAIN ERROR The right argument has the proper rank 


and length, but is not integer-valued or 
exceeds 32,767. Or, the tie number or 
component number is zero or a negetive 
number. 


DRIVE NOT READY An attempt has been made to use an empty, 
open, or non-existent disk drive. 


FILE ACCESS ERROR The user is not permitted to replace 


components of this file, or the 
passnumber is incorrect. 
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FILE DAMAGED 


FILE FULL 


FILE INDEX ERROR 


FILE TIE ERROR 


LENGTH ERROR 


RANK ERROR 


Invalid values have been found in the 
file component directory, possibly from 
having removed the disk while the file 
was tied. 


The space required for the new component 
value would cause the file to exceed its 
file reservation, 


The component number given lies outside 
the file component number limits. 


The file tie number is not tied to a 
file. 


The right argument has the proper rank, 
but does not have exactly two or three 
elements. 


The right argument is not a vector or 
singleton. 
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DFRESIZE 


The dyadic function CFRESIZE resets the amount of disk 
space reserved (size limit) for a file. 


Syntax 


limit DFRESIZE tieno 
imit [FRESIZE t, 


passno 


- a non-negative integer giving the file size 
limit in bytes 

- a positive integer file tie number 

- an integer passnumber 


The left argument is the new file reservation (size 
limit) in bytes. It should be a non-negative integer 
greater than or equal to the current size of the file, or 
zero (for no-limit). The left argument must be an 
integer-valued singleton. 


The right argument designates the file (by file tie 
number) and passnumber. If the passnumber is omitted, it is 
assumed to be zero. The right argument must be an 
integer-valued singleton or tvo-element vector. 


Result 


The function ijPRE$I2E does not return an explicit 
result. 


Effect 


The specified number of bytes of disk storage is 
reserved for the file. Since DOS disk storage is allocated 
in multiples of 512 bytes, a file reservation which is an 
exact multiple of 512 wastes no bytes on the disk. 


1f the specified limit is zero, the file size limit is 
set to no-limit (up to the maximum capacity available in the 
library where the file is stored). This means that the file 
has no disk space reserved for it beyond that which it is 
already occupying. but also that it has no grovth limit 
imposed upon it. Disk space is added as needed; the default 
size of disk space additions is 4,096 bytes. The default 
size of disk space additions can be changed to other 
multiples of 512 bytes using [JPOKE. A newly created file in 
the APL«PLUS/PC System has a default file reservation of 
zero if no other reservation is specified. 
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Access 


The file must be tied, the passnumber must match the 
one in effect, and the user must have resize access. 


The access code for JFRESIZE is 1024. 


Example 


JESIZE 27 
1 50 9472 10240 


(SE3+("FSIZE 27){4]) CFRESIZE 27 


ZFSIZE 27 
1 $0 9472 15240 


0 OFRESIZE 27 o [FSIZE 27 


1 50 9472 0 


Error Reports 
DISK ERROR 


DISK FULL 


DISK WRITE 
PROTECTED 


DOMAIN ERROR 


DRIVE NOT READY 


FILE ACCESS ERROR 


FILE DAMAGED 


FILE SIZE ERROR 


FILE TIE ERROR 


A disk error has occurred, probably due 
to a hardware fault or to an unformatted 
or defective disk. 


The specified reservation exceeds the 
available space on the disk. 


The disk now in the disk drive has a 
protective cover over its notch 
preventing any alteration of its 
Contents. 


The left argument has the proper rank and 
length, but is not a non-negative 
integer. Or, the left argument exceeds 
2107483647. The right argument has the 
proper rank and length, but is not 
integer-valued or exceeds 32767. Or, the 
tie number i's zero or negative. 


An attempt has been made to use an empty, 
open, or non-existent disk drive. 


The user is not permitted to resize this 
file, or the passnumber is incorrect. 


Invalid values have been found in the 
file component directory, possibly from 
having removed the disk while the file 
was tied. 


The specified reservation is less than 
the amount already in use but not zero. 


The file tie number is not tied to a 
file. 
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LENGTH ERROR The right argument has the proper rank, 
but does not have exactly one or two 
elements. 


RANK ERROR The right argument is not a vector or 
singleton. 
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DESIZE -- File Si 


Information DFSIZE 


The monadic system function CFSIZE returns a vector 
Containing information about the size limits of a file. 


Syntax 


result + “FSIZE tieno 
result + .FSIZE tieno passno 


result - the explicit result 
tieno - an integer file tie number 
passno - an integer passnumber 


Argument 


The argument designates the file (by file tie number) 
and the passnumber. If the passnumber is omitted, it is 
assumed to be zero. The argument must be an integer-valued 
Singleton or two-element vector. 


Result 


The explicit result of JFSIZE is currently a 
four-element numeric vector containing the following 
information: 


[1] the number of the first component in the file 


[2] one plus the number of the last component in the 
file 


[3] the physical storage (in bytes) used by the file, 
including data, overhead, and access matrix, but 
not including unused portions of reserved space 


[4] the file reservation in bytes, or 0 (a value of 
zero means no upper limit). 


Access 

The file must be tied and the passnumber must match the 
one in effect. No special access code is required for 
'SIZE; if the user has any form of access to the file, 
‘SIZE can be used. 


Example 
10 PRIMES’ DFSTIE 37 
T 


OFSIZE 3 
1 53 28672 30208 
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Error Reports 


DOMAIN ERROR The argument has the proper rank and 
length, but is not integer-valued, 
exceeds 32767, or contains a tie number 


of zero. o 

FILE ACCESS ERROR The passnumber is incorrect. 
FILE TIE ERROR The file tie number is not tied to a 

tile. 
LENGTH ERROR The argument has the proper rank, but 

does not have exactly one or tvo 

elements. 
RANK ERROR The argument is not a vector or 

singleton. 
VS FULL The explicit result requires more 


workspace storage than is available. 
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uESTAC -- File Set of Access Matrix CFSTAC 


The dyadic system function TFSTAC sets the access 
matrix for a file. 


Syntax 


access CFSTAC tieno 
access CFSTAC tieno passno 


access - a three-column integer matrix or a three-element 
integer vector 
tieno - a positive integer file tie number 
Ràssno - an integer passnumber 
Arguments 

The left argument is the new access matrix. It must be 
a three-column integer matrix or a three-element integer 
vector. 

The right argument designates the file (by file tie 
number) and passnumber. If the passnumber is omitted, it is 
assumed to be zero. The right argument must be an 
integer-valued singleton or two-element vector. 

Result 

The function “FSTAC does not return an explicit result. 
Effect 

The access matrix for the file is replaced. The new 
access restrictions are imposed on a user when he next ties 
or re-ties the file. 

For files with no limit on their growth (a file 
reservation of 0), FST4C may increase the amount of disk 
storage occupied by the file. 

Access 

The file must be tied, the passnumber must match the 
one in effect, and the user must have the authority to 
change the access matrix. 

The access code for [FS74C is 8192. 

Example 
(2 3 pÜAI[i), 75 7655 12304 71 0) [FSTAC 33 7655 


010 [IFSTAC TIENO 
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Error Reports 
DISK ERROR 


DISK FULL 


DISK WRITE 
PROTECTED 


DOMAIN ERROR 


DRIVE NOT READY 


FILE ACCESS ERROR 


FILE DAMAGED 


FILE FULL 


FILE TIE ERROR 


LENGTE ERROR 


RANK ERROR 


A disk error has occurred, probably due 
to a hardware fault or to an unformatted 
or defective disk. 


The operation cannot be done in the 
available system storage. Use [IFERASE, 
GNERASE, LFDUP, or )DROP to eliminate 
unneeded storage and try again. 


The disk now in the disk drive has a 
protective cover over its notch 
preventing any alteration of its 
contents. 


The left argument is not a valid access 
matrix, or an argument is not 
integer-valued or contains a value 
outside the range 32,768 to 32,767. Or, 
the tie number is zero or a negative 
number. 


An attempt has been made to use an empty, 
open, or non-existent disk drive. 


The user is not permitted to set the 
access matrix for this file, or the 
passnumber is incorrect. 


Invalid values have been found in the 
file component directory, possibly from 
having removed the disk while the file 
was tied. 


Writing the given access matrix to the 
file would have caused the file to exceed 
its file size limit (reservation). 


The file tie number is not tied to a 
file. 


The right argument has the proper rank, 
but does not have exactly one or two 
elements. 


The right argument is not a vector or 
singleton, 
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DESTIE . 


e Tie UFSTIE 


The dyadic system function J]FSTIE establishes a file 
tie. While not distinct from DFTIE in the APL*PLUS/PC 
System, -FSTIF is allowed for compatibility with other 
APL*PLUS Systems, where it permits simultaneous use by 
multiple users. 


Syntax 


'fileid' -FSTIE tieno 
'fileid' _FSTIE tieno passno 


fileid - a character vector or singleton containing a 
file name, optionally preceded by a library 
number 

tieno - a positive integer file tie number 

passno - an integer passnumber 


Arguments 


The left argument designates the file identification of 
an existing file. If the library number is omitted, the 
current default library is used. The left argument must be 
a Character vector or singleton, containing only digits, 
letters 4 through 2, and spaces. 


The right argument designates an available file tie 
number and a passnumber. 1f the passnumber is omitted, it 
is assumed to be zero. The right argument must be an 
integer-valued singleton or two-element vector. 

Result 

The function “FSTIE does not return an explicit result. 
Effect 

The file is tied. 

Access 

The file must exist, the user must have some form of 
access to the file, and the passnumber must match the one in 
the access matrix of the file. No special access code is 


required for [JESTIE; if the user has any form of access to 
the file, the file can be tied. 
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A file that is already tied with [FSTIE or DFTIE can be 
re-tied using DFSTIE or OFTIE without an intervening untie, 
using the same tie number or a different one. The only 
restrictions are that no other file may already be tied with 
the new tie number and the file cannot be tied to a negative 
number (with DNTIE). This "slippery" tie can be used to 
verify that a file is tied (without looking up its name in 
ÜFNAMES), to change the passnumber associated with the file 
tie (for cases where the access matrix permits different 
access with different passnumbers), or to change the degree 
of access permitted (if the access matrix has changed since 
the file was originally tied). 


If non-default libraries have been defined by an 
APLLIBS file (see Al e System User's Gui 
(STSC, 1983)) and t brary numbers refer to 
identical paths, a “FTTE of a file that is already tied in 
an identical (but differently numbered) path is treated as a 
slippery tie and merely changes the library number of the 
existing file tie. 


Examples 
"PRIMES' ÜFSTIE 37 0 . . . © 'PRIMES' LFSTIE 3? 747 
"1 PRINTOUT! ÜFSTIE 33 30117 


Error Reports 


DISK ERROR A disk error has occurred, probably 
due to a hardware fault or to an 
unformatted or defective disk. 


DOMAIN ERROR The right argument has the proper 
rank ahd length, bot is not 
integer-valued or exceeds 32,767. 
Or, the tie number is a zero or à 
negative number. 


DRIVE NOT READY An attempt has been made to use an 
empty, open, or non-existent disk 
drive. 


FILE ACCESS ERROR The user is not permitted any form 
of access to this file, the 
passnumber is incorrect, or the 
access matrix is damaged. 


FILE ARGUMENT ERROR The left argument is ill-formed, 
numeric, or not a vector or 
singleton. 


FILE DAMAGED Invalid values have been found in 
the file component directory, 
possibly from having removed the 
disk while the file was tied. 
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FILE NOT FOUND 


FILE TIE ERROR 


FILE TIE QUOTA EXCEEDED 


INSUFFICIENT HANDLES 


LENGTH ERROR 


LIBRARY NOT FOUND 


RANK ERROR 


The file named in the argument is 
not in the specified or default 
library. 


The specified file tie number is 
already tied to another file. Or, 
the specified file is still tied 
from an earlier use of ONTIE. 


Performing the operation would have 
caused the user to have more than 
the maximum number of files (twenty) 
tied at once. 


The maximum number of files that DOS 
allows open at one time would be 
exceeded. If you can untie a file, 
you can free a handle for the 
attempted operation. To increase 
the number of handles available, 
include FILES=n (where n is 5 more 
than the desired file tie quota) in 
your CONFIG.SYS file and reboot the 
System. For the default file tie 
quota of 10, use FILES=1S. 


The right argument has the proper 
rank, but does not have exactly one 
or two elements. 


The APL library (DOS directory) you 
are trying to use cannot be found on 
the disk in the disk drive indicated 
by DLIB$. Failure to find the 
library may result from not 
including a space between the 
library number and file name. 


The right argument is not a vector 
or singleton. 
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ETIE File Tie DFTIE 


The dyadic system function ÜFTIE establishes a file 
tie. In the APL*PLUS/PC System, it is not distinct from 
DFSTIE. 


Syntax 


'fileid' OFTIE tieno 
'fileid' JFTIE tieno passno 


fileid - a character vector or singleton containing a 
file name, optionally preceded by a library 
number 

tieno - a positive integer file tie number 

passno ~ an integer passnumber 


Arguments 


The left argument designates the file identification of 
an existing file. If the library number is omitted, the 
current default library is assumed. The left argument must 
be a character vector or singleton, containing only digits, 
letters 4 through Z, and spaces. 


The right argument designates an available file tie 
number and a passnumber. If the passnumber is omitted, it 
is assumed to be zero. The right argument must be an 
integer-valued singleton or two-element vector. 


Result 


The function DFTIE does not return an explicit result. 


Effect 


The file is tied. 


Access 


If the file was already tied to some other number with 
DFTIE or JFSTIE, the old tie is replaced by the new one. 


The file must exist. No special access code is 
required for QFTIE in the APL*PLUS/PC System; if the user 
has any form of access to the file, the file can be tied. 
On other APL*PLUS Systems, the access code for []FTIE is 2. 


A file that is already tied with UFSTIE or CFTIE can be 
re-tied using either [FSTIE or CFTIE without an intervening 
untie, using the same tie number or a different one. The 
only restrictions are that no other file can already be tied 
with the new tie number and the file cannot be tied to a 
negative number (with [NTIE). This "slippery" tie can be 
used to verify that a file is tied (without looking up its 
name in CFNAMES), to change the passnumber associated with 
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the file tie (for cases where the access matrix permits 
different access with different passnumbers), or to change 
the degree of access permitted (if the access matrix has 
changed since the file was originally tied). 


1f non-default libraries have been defined by an 
APLLIBS file (see the Fil stem User" uide) and two 
different library numbers refer to identical paths, a UFSTIE 
of a file that is already tied in an identical (but 
differently numbered path) is treated as a slippery tie and 
merely changes the library number of the existing file tie. 


Examples 
'0 PRIMES’ [JFTIE 37 o . . . o 'O PRIMES' QFTIE 37 747 


‘PRINTOUT’ [FTIE 33 30117 


Error Reports 


DISK ERROR A disk error has occurred, probably 
due to a hardware fault or to an 
unformatted or defective disk. 


DOMAIN ERROR The right argument has the proper 
rank and length, but is not 
integer-valued or exceeds 32,767. 
Or, the tie number is zero or a 
negative number. 


DRIVE NOT READY An attempt has been made to use an 
empty, open, or non-existent disk 
drive. 

FILE ACCESS ERROR The user is not permitted any form 


of access to this file, the 
passnumber is incorrect, or the 
access matrix is damaged. 


FILE ARGUMENT ERROR The left argument is ill-formed, 
numeric, or not a vector or 
singleton. 


FILE DAMAGED Invalid values have been found in 
the file component directory. 


FILE NOT FOUND The file named in the argument is 
not in the specified or default 
library. 


FILE TIE ERROR The specified file tie number is 
already tied to another file. Or, 
the specified file is stíll tied 
from an earlier use of INTIZ. 
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FILE TIE QUOTA EXCEEDED Performing the operation would have 
caused the user to have more than 
the maximum number of files (twenty) 
tied at once. 


INSUFFICIENT HANDLES The maximum number of files tnat DOS 
allows open at one time would be 
exceeded. If you can untie a file, 
you can free a handle for the 
attempted operation. To increase 
the number of handles available, 
include FILES=n (where n is 5 more 
than the desired file tie quota) in 
your CONFIG.SYS file and reboot the 
system. For the default file tie 
quota of 10, use FILES=15. 


LENGTH ERROR The right argument has the proper 
rank, but does not have exactly one 
or two elements. 


LIBRARY NOT FOUND The APL library (DOS directory) you 
are trying to use cannot be found on 
the disk in the disk drive indicated 
by LLIBS. Failure to find the 
library may result from not 
including a space between the 
library number and file name. 


RANK ERROR The right argument is not à vector 
or singleton. 
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ÜFUNTIE 


The monadic system function []FUNTIE unties designated 
APL component files. 


e™ 
LFUNTIE tienol tieno2 eno3 . . 


tieno - an integer file tie number 


The argument designates the file tie numbers of the APL 
component files to be untied. The argument can be à 
singleton or a vector of zero or more file tie numbers. 
Elements of the argument do not have to be distinct, nor 
must they designate tied files. An empty vector is 
permitted as an argument, and does not affect any file ties. 
The argument must be a numeric vector or singleton. 


Result 


The function [JFUNTIE does not return an explicit 
result. 


Effect 
The files tied to any of the tie numbers in the 
argument are untied. This frees the file tie slot for 
possible re-use vith another file. 
WARNING: To avoid damaging your files always make sure that 
the disk that was in the disk drive when you tied 
a file is in that disk drive when you untie that 
file. 
Untying files before inserting a different disk in the 
same disk drive helps avoid FILE DAMAGED errors that can be 


caused by attempting to read or write to a tied file no 
longer on a disk in that disk drive. 


Access 


No passnumber is used and no special access code is 
required. 


Examples 
DFUNTIE 33 


LFUNTIE LFNUMS 
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Error Reports 


DOMAIN ERROR The argument has the proper rank, but is 
not integer-valued; the argument contains 
a zero, 8 fractional value, or à value 
outside the range 1 to 32,767; or, the 
argument is character-valued. e 


DRIVE NOT READY An attempt has been made to use an empty, 
open, or non-existent disk drive, possibly 
at the direction of an APLLIBS file. 


RANK ERROR The argument is not a vector or singleton. 
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- Function Fix DrX 


The monadic system function [FX defines (fixes) a 
function from the Canonical representation of the function. 


suis e 
result + [Fx fnrep 


resylt - the explicit result 
ep - the character representation of a function 


Argument 


The argument to [FX is a character matrix containing 
the character representation of a function. The form of the 
Character representation is similar to the result of JCR. 
Thus, the lines of the matrix should not contain bracketed 
line numbers, nor should they contain the characters V or ¥ 
other than in comments or character constants. Blanks that 
wag be superfluous in function definition mode are ignored 
by Fx. 


Result 


1f the function definition is successful, the explicit 
result of JFX is a character vector containing the name of 
the function defined. 


If the function definition is not successful, the 
result is a numeric scalar containing the index of the row 
in the matrix argument where the first fault was found. The 
result may indicate a row that does not exist in the 
argument if the argument is empty or if the error is 
detected after the last row of the argument. The index 
returned depends upon the value of 310. 


Effect 


Unless an error condition occurs, the specified 
function is defined in the active workspace. The amount of 
available workspace area and the number of symbols may 
change. 


1f the name of the function that has been defined 
corresponds to a local identifier in a currently executing, 
pendent, or suspended function, the newly defined function 
is local to that function and is erased when the function in 
which it is localized completes execution. 


1f the name of the function that has been defined 
corresponds to the name of an existing function, the 
existing function is replaced and any i/STOP or _TRACE 
settings in the function are removed. 
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Example 


M-CCR 'DISPLAY' o V-DVR 'DISPLAY' 


Orx 
DISPLAY 
DFX Y 
RANK ERROR 
DFX v 
Error Reports 
DOMAIN ERROR The argument has the proper rank but is 
not character-valued. 
RANK ERROR The argument is not a matrix. 
WS FULL The explicit result requires more 


workspace storage than is available, 
Comparison of FY with [DEF 


ÜFX and (DEF provide similar capabilities. They are 
compared under "(DEF -- Function Definition". 
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D&CIRCLE -- Draw Circles, Ellipses, Arcs, and Pies [CIRCLE 


Systems. 
Syntax 
color [GCIRCLE arcspec 


color - an integer singleton, vector or matrix 

arcspec - specification of one or more arcs (each having 
from 3 to 7 elements) as a vector, matrix or 
rank 3 array 


Arguments 


The left argument of [|GCIRCLE defines the color pattern 
to be used. It can be an integer singleton, vector, or 
matrix. The color choices in the left argument are re-used 
cyclically until no more are needed. 


The right argument of “GCIRCLE defines the parameters 
for drawing one or more circular figures. The parameters 
set by each column of the right argument are 


Column = Parameter Default 
1 X coordinate of center (none) 
2 Y coordinate of center (none) 
3 radius (horizontal) (none) 
4 initial angle (in radians) 0 
5 terminal angle (in radians) 6,28 
6 aspect ratio (heighttwidth) 1 
1 angular displacement (in radians) 0 


Columns 4, 5, 6 and ? need not be specified. 
Effect 


ÜGCIRCLE draws figures according to the parameters 
specified in its arguments. 


When the left argument of DGCIRCLE is a singleton, 
vector, or matrix vith one rov, all objects are drawn with 
the repeating color pattern specified by this argument. If 
the left argument of [GCIRCLE is a matrix, each object 
specified by the right argument is drawn in the colors 
specified by the corresponding row of the left argument. 


The color choices in the left argument are re-used 
cyclically until no more are needed. 
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The manner in which the shape of the right argument of 
ÜGCIRCLE determines the type of figure drawn is described 
below. 


If the right argument of JGCIRCLE is a vector of length 
3, a circle is dravn vhose center and radius are specified 
by the right argument. 


If the right argument of JGCIRCLE is a vector of length 
5, an arc of a circle of center and radius specified by the 
first three elements of the right argument is drawn. The 
initial and terminal angles of the arc are specified by the 
fourth and fifth elements of the right argument. These 
arguments are measured in radians clockwise from the 3:00 
position. (A radian is 360102 degrees.) If the difference 
between the terminal angle and initial angle is positive, 
the arc is drawn in a clockwise direction: if this 
difference is negative, the arc is drawn in a 
counter-clockvise direction. 


If the right argument of CGCIRCLE is a vector of length 
6, an elliptical arc (or entire ellipse) is drawn. The 
sixth element defines the aspect ratio of the ellipse (the 
ratio of its height to its width) and the other five entries 
of the right argument determine its center, (horizontal) 
radius, and initial and terminal angles. 


The seventh element of the right argument is the 
displacement angle of the circular (elliptical) figure to be 
drawn, When this element is 0 or unspecified, the axes of 
the figure are aligned vith the coordinate axes. When the 
seventh element is different from 0, the axes of the 
circular figure are rotated in a clockwise direction by the 
angle specified (measured in radians). 


If the right argument of GGCIRCLE is a matrix, the 
Circles, arcs, or elliptical arcs defined by each of its 
rows are drawn. 


If the right argument of CGCIRCLE is an array of shape 
1 by 1 by M columns where M is 3, 4, 5, 6, or 7, a 
pie-shaped wedge is drawn. Its center, radius, initial and 
terminal angles, aspect ratio, and angular displacement are 
specified by the columns of the array. 


If the right argument is a 1 by N by M array, then N 
pie-shaped wedges are drawn according to the parameters set 
by each row of the array. 


NOTE: Since most screens are not square, circles drawn 
with the default aspect ratio of 1 often do not appear round 
(see "Graphics Overview" in the User's Guide). To make 
circles appear round, you can either make the screen aspect 
ratio 1 (using either [];VIEW or ÜGWINDOW), or you can set 
the sixth element of the right argument of DGCIRCLE to 
Correct for the uneven scaling of the coordinates on the 
display monitor (see the examples below). 
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The following table summarizes how the shape of the 
DGCCIRCLE right argument determines the type of figure and 
how the left argument controls the figure colors. In the 
following table, a five-column right argument covld also 
have six or seven columns. 


Left Arg. Right Arg. ] . 
—BShape . . Shape. Figure, Coloring 


Circle in a solid color 

circles in a solid color 

circle in a multicolor pattern 
circles in a multicolor pattern 
circles in p multicolor patterns 


Poppe 


5 an arc in a solid color 
5 n arcs in a solid color 
5 an arc in a multicolor pattern 
5 n arcs in a multicolor pattern 
5 n arcs in p multicolor patterns 


L- 
honcoo Hanes 


i] 


wedge in a solid color 

wedges in a solid color 

wedge in a multicolor pattern 
wedges in a multicolor pattern 
wedges in p multicolor patterns 


nnn n 
sunm 


1. Draw a circle of color 1 centered at 500 500 with a 
radius of length 100: 


500 100 


2. If your monitor has a 24 by 18cm display, draw a round 
circle of color 1 centered at 500 500 with radius 100: 


1 DGCIRCLE S00 500 100 0 6,28,(24#18) 


3. Draw an arc from the 12:00 o'clock position to the 6:00 
o'clock position (a 180-degree or a pi-radian arc): 


1 DGCIRCLE 500 500 100 1.57 71.57 


4, Draw a pie-shaped wedge from the 3:00 o'clock position 
to the 6:00 o'clock position: 


1 [GCIRCLE 1 1 5p 500 500 100 O 1.57 
5. Draw an ellipse with aspect ratio 2: 
1 ÜGCIRCLE 500 500 100 0 6.28 2 


6. Draw an ellipse with aspect ratio 2 having its 
horizontal axis rotated 45 degrees clockwise: 


1 DeCIRCLE 500 500 100 0 6.28 2 0.785 
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7. Draw two circles each colored with alternating pixels of 
color 1 and color 2: 


1 2 DGCIRCLE 2 30300 300 100 600 300 100 


8. Draw two circles, one of color 1 and the other of color & 


JGCIRCLE 2 30300 300 100 600 300 100 


DOMAIN ERROR The left argument is not integer-valued. 


LENGTH ERROR The right argument does not have between 
three and seven elements. 


RANK ERROR The left argument has rank greater than 


2, or the right argument has rank 
greater than 3. 
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IGINIIT -- Ini 


Initialize Graphics OGINIT 
Graph. 


The dyadic system function DGINIT initializes the 
graphics display for the particular graphics adapter in use, 


selecting 
retaining 


resolutions and palettes, while clearing or 
any graphic images already on the screen and 


graphics easel. See "Graphics Overview” in the User's 
Guide. It also identifies the graphics adapter board 
already initialized. [I]GINIT, as described here, is specific 
to the APL*PLUS/PC System; it may be different or absent in 
other APL*PLUS Systems. 


Syntax 


parans 
boardname - a character vector specifying a graphics 
adapter or an empty character vector 


Arguments 


+ params [¢INIT 'boardname' 


- the explicit result 
- an integer singleton or vector 


The left argument is an integer vector or singleton. 
The meaning of each element of the left argument is 


described 
Element 


[11 


t21 


[31 


ts] 


Copyright 


below: 
Parameter 


Card mode -- an integer specifying the numbers of 
colors used and the screen resolution. 


Palette -- an integer specifying a palette from 
which the colors are chosen (by writing a byte to 
the palette port). Using a value of 0 for the 
palette vill give the non-zero default appropriate 
to the card. Use 0 here for the IBM EGA in mode 
^. 5, 6, or 7, which ignores this item. 


Clear flag -- a 0 clears all previous graphics 
display, a 1 retains previous image. 


Except for the IBM EGA, base segment address -- 
the segment address of the start of graphics 
display memory. This must be specified for 
adapters such as the ORCHID and SCION boards. The 
value of this element is computed using the 
formula: 


S+(base segment address) + 256 
For the IBM EGA, overscan (border) color -- an 
integer between 0 and 63 inclusive specifying the 
color. The default is 0. 


Unused except for the IBM EGA, Use 0 here to 
position remaining parameters for other adapters. 
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[51 The IBM EGA can use 64 colors (0-63), but only 16 

to at a time. The graphics system functions use this 

[20] palette of sixteen colors (0-15). If positions 
[5] through [20] are omitted, a default palette is 
used. If some or all of these positions are used, 
the IBM colors listed replace the default colors 
for those positions in the palette. See the 
Section on the IBM EGA for a list of the default 
values. 


[61 ORCHID board only, wait -- how many retrace 
intervals (each 50 milliseconds) to wait before 
flipping the ORCHID board on, The ORCHID adapter 
board must be turned off during drawing. This 
setting allows you to set the intervals at which 
you can monitor the progress of a slow graphics 
routine. A useful setting for this parameter is 


20. 
[7] ORCHID board only, number of retraces to leave the 
ORCHID board on (see item 6, above). A useful 


setting for this parameter is 10. 


NOTE: With the exception of the ORCHID graphics 
adapter board, a singleton left argument will suffice to 
initialize graphics. The ORCHID board requires at least 
four elements in the left argument. 


The right argument of DGINIT is either a character 
vector that specifies the type of graphics adapter board 
being used, or an empty character vector. A right argument 
of an empty character vector vill result in the boardname 
that is currently initialized. Similarly, you can query the 
left argument of CGINIT as it was most recently invoked, by 
executing: 


1 S6INIT 1 


The result will be a vector of up to seven elements 
representing the most recently invoked left argument of 
DGINIT. 


The graphics adapter will switch from text mode to 
graphics mode, and remain in graphics mode until the 
keyboard unlocks for immediate execution (which then forces 
an exit to text mode). There is a [J]POKE available to 
prevent an exit to text mode, causing the adapter to remain 
in graphics mode. 


You can force an exit from graphics mode during 
program execution by pressing Exit. This action forces à 
return to text mode, and restores display of the previous 
text screen. 


The graphics initialization settings for the currently 
supported graphics adapter boards are listed below. 


Copyright 1983 STSC, Inc. 3-127 System Functions 


HERCULES Monochrome Adapter 


(0,0,c) DGINIT 'HERCULES' 


Resolution: 720 348 Display: tvo-color, 
graphics display 
e (1,0,c) DGINIT ‘HERCULES’ 
Resolution: 720 348 Display: two-color, 


text display 
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***HARNING: Using DGINIT with values for a graphics adapter 
that is not installed in your computer may lead 
to physical damage of your installed equipment, 
particularly your monitor. For exanple, 
executing 0 ÜGINIT ‘HERCULES’ when the computer 
only has a monochrome display adapter card 
installed will result in damage to the 
monochrome monitor, 


IBM Color Adapter or fully compatible equivalent 


(0,p,c) DGINIT 'IBMCOLOR' 
Resolution: 320 200 Display: four-color 


(p.c) DGINIT 'IBMCOLOR' 
Resolution: 640 200 Display: two-color 


IBM Enhanced Graphics Adapter 


(2,0,c.b,c) (IGINIT ‘IBMCOLOR' 
Resolution: 320 200 Display: sixteen-color 


(5,0,c, b.c) DGINIT 'IBMCOLOR' 
Resolution: 640 200 Display: sixteen-color 


(6,0, c,0,p) INIT 'IBMCOLOR' 
Resolution: 640 350 Display: four-color for 
Enhanced Color Display 
(see note below for 
palette color setting) 


(7,0,¢) DGINIT 'IBMCOLOR' 
Resolution: 640 350 Display: four-color 
monochrome 


NOTE: Colors modes 4 and $ initialize either the IBM Color 
Display monitor or the IBM Enhanced Color Display 
Monitor. 


Palette colors are integers between 0 and 63, specifying one 
of the 64 possible IBM EGA color values. The palette is 
composed of a maximum of 16 color values. Specifying no 
color values or a partial color palette (less than 16 
values) will result in use of the default color values. The 
Color number and corresponding default color values are 
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olor Number Color Value Actual Color 


o 0 Black 
1 1 Blue 

2 2 Green 

3 3 Cyan 

4 4 Red 

5 5 Magenta 

8 6 Brown 

J. 7 White 

8 56 Dark grey 

9 37 Light blue 

10 58 Light green 

11 59 Light cyan 

12 50 Light red 

13 $1 Light magenta 

14 62 Yellow 

5 53 Intensified white 


1f you want to modify only color numbers 3 and 4, you need 
to specify color values for color numbers 0 thru 4. To 
change the entire palette specify 16 color values. 


Color mode ? initializes a monochrome display monitor. 
The palette is composed of four colors: black, video. 
blinking video, and intensified video. The border and 
palette color cannot be modified. 


HERCULES Monochrome Adapter 


(0,0,¢) IGINIT 'HERCULES' 
Resolution: 720 348 Display: two-color, 
graphics display 


(1,0,¢) TGINIT 'HERCULES" 
Resolution: 720 346 Display: two-color, 
text display 


NOTE: It is sometimes useful with the Hercules graphics 
adapter to alternate between the graphics and text 
displays when composing or debugging graphics programs. 
Since the Hercules adapter has separate screen memory 
for graphics and text displays, you need not lose the 
graphics image in memory when switching back to text 
display. After initializing the graphics memory with: 


O LGINIT 'HERCULES' 
you can return to text display with: 


1 GGINIT ‘HERCULES’ 
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It is easy to execute individual graphics primitives 
that write to the screen, or to debug graphics programs 


while in text display. 
enter: 


0 0 1 “GIWIT 'HERCULES' 


To see the graphics displayed, 


You can continue to switch back and forth between the 


text and graphics displays. 
AMDEK Color Adapter 


(0,p,Cc) GCINIT 'AMDEK' 
Resolution: 320 200 


(1.p.c) DGINIT 'AMDEK" 
Resolution: 640 200 


(2.p.C) CGINIT 'AMDEK" 

Resolution: 320 200 
(3,p,c) DGINIT 'AMDEK" 
Resolution: 640 200 


(Oi,p.c) DGINIT 'AMDEK* 
Resolution: 320 400 


(5,p.c) DGINIT 'AMDEK' 
Resolution: 640 400 


(0.p.c) DGINIT 'TECMAR' 
Resolution: 320 200 


(1,p,¢) DGINIT 'TECMAR' 
Resolution: 640 200 


(2.p,c) OGINIT 'TECMAR' 
Resolution: 640 200 


(3.p.c) DGINIT 'TECMAR' 
Resolution: 640 400 


(8.p,c) DGINIT 'TECMAR' 
Resolution: 720 200 


(5,p,c) OGINIT 'TECHAR' 
Resolution: 720 400 


(6.p,c) “GINIT 'TECMAR' 
Resolution: 720 352 


C.p.c) IJGINIT 'TECMAR' 
Resolution: 720 704 
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CMAR Color or Monochrome Adapter 


Display: four-color 


Display: two-color 


Display: sixteen-color 


Display: four-color 


Display: sixteen-color 


Display: four-color 


Display: four-color 


Display: two-color 


Display: sixteen-color 


Display: sixteen-color 


Display: four-color 


Display: four-color 


Display: three-gray on 
monochrome monitor 


Display: three-gray on 
monochrome monitor 


System Functions 


NQTE: The switch on the back of the Tecmar graphics 
adapter must be in the up position for use with a 
monochrome monitor, and in the down position for use 
with a color monitor. If the switch is in the vrong 
position, DGINIT will result in a DOMAIN ERROR. You 
Should also verify that the JPR1 switch C is in the on o 
position (the other switches for JPR1 are irrelevant), 
and that the JPR7 switch is also in the on position if 
the card is used with the monochrome monitor. The 
JPR? switch can be either on or off when the card is 
used with a color monitor. 


QRCHID Monochrome Adapter 


(0 O,c.s,0.f.n) LGINIT 'ORCHID' 
Resolution: 720 348 Display: two-color 


NOTE: The default dip-switch settings for the ORCHID 
monochrome adapter board place graphics memory in a 
portion of RAM that is often used for computation. 
This can be avoided by setting the svitches on the 
ORCHID board to E000hex (switch 1 on, all others off) 
which specifies an unused portion of ROM memory as the 
starting address of the graphics memory segment. The 
Corresponding value for the fourth element of the left 
argument of GGINIT is 224; for example. 


0 0 0 224 0 20 10 DGINIT 'ORCHID' 


SCION Color Adapter o 


'SCION' 
650 480 Display: sixteen-color 


NOTE: The recommended base segment address for 
graphics memory is 8000hex, corresponding to 128 used 
as the fourth element of the left argument to JGINIT. 


AT&T Super Graphics 


0 DGINIT 'ATTSUPER' 
Resolution: 640 400 Display: four-color 


EPSQN or IBM Graphics Printer with No Graphics Adapter 


O DGINIT 'PRINTER' 
Resolution: 640 200 Display: two-color 


CGINIT 'PRINTER' 
Resolution: 720 350 Display: two-color 


» 


DGINIT 'PRINTER' 
Resolution: 747 960 Display: two-color [ 
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NOTE: To use an EPSON MX, RX, or FX series or IBM 
graphics printer, the APL session must be started with 
enough memory selected by using the R= startup option 
to match the left argument of [GINIT ‘PRINTER’. For 
option 0, use R-16; for 1, use R=31: for 2, use R=89. 


Result 
The result of DGINIT is the character vector 


identifying the graphics adapter card currently initialized, 
or a vector of blanks if no card has yet been initialized. 


UsrwiT-Dependent Primitive and System Functions 


No primitive functions depend upon the ÜGINIT setting. 
The setting affects the system functions [IGMASK, OGTYPE, 
DevIEW, DGWINDOW, and []6Z00M, whose settings UGINIT always 
reinitializes to the default values. 


Effect 


When OGINIT is used to initialize graphics, it does the 
following things: 


* Turns on the graphics controller chip. 

* Initializes the controller chip to the specified 
adapter board, screen configuration, and palette; 
where appropriate, sets the graphics memory segment 
to the address specified. 


* Clears the graphics screen unless the third element 
of the left argument is 1. 


* Sets the graphics state-setting functions to their 
Gefault values. These are 


Function Default value Effect 


OcMASK 7a No mask 
DeTYPE 9 Set 
Ocvrew 0 0 1023 1023 Full screen 


DÜGWINDOW 0 O 1023 1023 Full easel 
De200M 1 No magnification 


When both a monochrome and color monitor are used 
simultaneously, the APL*PLUS/PC System allows you to write 
text material on the monochrome monitor and have graphics 
displayed on the color graphics monitor. This configuration 
permits immediate execution mode while in graphics display. 


The statement O [INIT '' has no effect. It returns 
the name of the graphics adapter board currently in use. 
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Using a Single Monitor for Graphi: Text 


For those computer configurations in which graphics 
display and text display share the same memory (for example, 
the IBM, AMDEK, or TECMAR color adapter boards used vith 
only a color monitor, or HERCULES monochrome adapter board 
used only with a monochrome monitor) all graphics should be 
done under program control. In particular, this means that 
whenever you use a graphics routine, you should first 
initialize graphics (using params CGINIT 
execute the functions, and then return to immediate 
execution mode using 3 [INT 16. 


The use of Exit not only returns to immediate execution 
mode, but clears the screen and returns to text display. 


When using a single display monitor, any non-graphics 
output to the screen will execute correctly, but will 
produce strange results on the display. Therefore, writing 
to the screen during graphics display should be done only 
with the DGERITE command. Moreover, interactive functions 
Should use CINKEY (rather than [] or 7) to accept keyboard 
input. 


NOTE: Any explicit output (such as T+ or the explicit 
result of LiGINIT or GWINDOW) that is not suppressed while 
in graphics display causes undefined results on the graphics 
display. This can be prevented by 0 0p or assignment; for 
example, 


X«0 1 0 LGINIT 'IBMCOLOR' 


Setting .A4LX and DELY to close graphics display helps 
avoid entering immediate execution mode while in graphics 
display rather than text display. 


A delay using 0 Op[INKEY permits viewing a graphics 
display on the same screen you use for immediate execution 
mode before 3 CINT 16 clears it in the process of restoring 
text display. 


Error Report 
DOMAIN ERROR The right argument is not the name of a 
currently supported graphics adapter 


board, or the left argument is not in 
the proper range. 
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LINE -- w Li in nd B OGLINE 


The dyadic system function OGLINE plots individual 
points, draws straight line segments, and fills rectangular 
bars on the graphics easel. See "Graphics Overview” in the 
User's Guide. Depending on the rank of its right argument, 
ÜGLINE allows you to plot individual points, connect a set 
of points with straight line segments, or to draw solid 
rectangular bars. The left argument allows you to specify 
the color pattern to be used, [GLINE, as described here, is 
specific to the APL*xPLUS/PC System; it may be different or 
absent in other APL*PLUS Systems. 


Syntax 
color OGLINE points 


&olor - an integer singleton, vector, or matrix 
points - an array of rank 2 or 3 


Arguments 


The right argument of DGLINE specifies the points to 
plot as (x,y) pairs, while its shape determines what type of 
figure is drawn. 


An individual point is specified by each row of a 
two-column matrix. The first column has the X coordinate, 
the second column the Y coordinate. 


Connecting lines are drawn between the points in the 
successive rows of the two-column matrix by adding a new 
first dimension of length one to the right argument, forming 
an array of rank 3. 


Solid bars are drawn for each row in a four-column 
matrix. Each row defines two diagonally opposite corners of 
a rectangular bar. The first tvo columns are the X and Y 
coordinates of one corner, and the last two columns are the 
Coordinates of the diagonally opposite corner. 


The left argument of [GLIWE defines the color pattern 
to be used. It is used cyclically, if needed, until all 
objects specified by the right argument have been matched to 
a color pattern. 


* For a singleton, the entire drawing is done in the 
color corresponding to that number. 


* For a vector, the entire drawing is painted in the 
repeating pattern of colors specified. 


* For a matrix, the object corresponding to each row 
is painted in the color pattern specified by that 
rov. 

The color patterns used by GGLINE are subject to the 

effects of [JEMASK, ()TYPE, and []o200M. 
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Effect 


CGLINE draws figures specified by its arguments. 


as a vector of shape 1) set the color pattern to be used. 
This pattern is repeated as many times as necessary to draw 
the figure specified. For example, if the left argument is 
11122, the pattern will contain a repeating sequence of 
3 pixels of color 1 followed by two pixels of color 2 
(assuming [16200M is 1 and ŪGMASK is ^1). When used in solid 
figures, the color pattern of each successive row is rotated 
one pixel to the left to produce dithered or striped 
effects. 


The rows of the left argument (a singleton is treated 


When the left argument of [GLINE is a singleton, 
vector, or matrix with one row, all objects are drawn with 
the same color pattern. If the left argument of IGLINE is a 
matrix, each object defined by the right argument is drawn 
in the color pattern specified by the corresponding row of 
the left argument. 


The colors or color patterns in the left argument are 
re-used cyclically until no more are needed. 


The manner in which the shape of the right argument of 
ZGLINE determines the type of figure drawn is described 
below: 


[ } * To plot a sequence of N points, make the right 
argument of CGLINE the N by 2 matrix in which each 
row contains the X and Y coordinates of the points 
to be graphed. 


* To draw a solid bar with diagonal corners X1,Yi and 
X2,Y2, make the right argument of J¢LINE a one-row 
matrix containing the ordered pairs (X1,¥1) and 
(X2,Y2). To draw solid bars, make the right 
argument of DGLINE o four-column matrix in which 
each rov defines a bar. 


* To connect a series of points with successive line 
segments, make the right argument of IGLINE the 1 by 
N by 2 array in which each row contains the X and Y 
coordinates of the points to be connected. DGLINE 
will connect the point specified by each row to the 
point specified by the next row. 


* If the right argument of DGLINE is an M by N by 2 
array, then M lines are drawn, each using N-1 
connected line segments. 


UGLINE supports clipping; that is, figures which have 
coordinates that are outside the easel boundaries are 
clipped at the boundaries. 
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The repetition factor for color patterns drawn with 
LINE can be changed with 56200M, and dotted and dashed 
Gravings can be made using “GMASK. “GTYPE determines the 
manner in which the new figure vill mix with the existing 
picture. 


The following table summarizes how the shape of the 
TGLINE right argument determines the type of figure and how 
the left argument controls the figure colors. 


Left Arg. Right Arg. . y 
Shape Shape Figure, Coloring 
2 a colored point 
2 n points in the same color 
2 D points in different colors 


2 a line in a solid color 
2 a line in a multicolor pattern 


8 i.n.2 n-1 connected lines in a solid 
color 
e 1.n.2 n-1 connected lines in a multicolor 
pattern 
EI 1.5.2 n-1 connected lines each in a solid 
color 
p.c 1.0.2 n-1 connected lines in p multicolor 
patterns 


e 5,2 2 n unconnected lines in a solid 
color 
e n.2 2 n unconnected lines in a multicolor 
pattern 
gil n.2 2 n unconnected lines each in a solid 
color 
pe n.22 n unconnected lines in p multicolor 
patterns 


e m.n,2 m sets of n-1 connected lines 
in a solid color 
4 O.n.2 m sets of n-1 connected lines 
in a multicolor pattern 
gl D.n.2 m sets of n-1 connected lines, 
each set in one of c solid 
colors 
Rs m.n.2 m sets of p-1 connected lines, 
each set in one of p multicolor 
patterns 


4 a solid-color bar 

u a bar in a multicolor pattern 

4 n solid-color bars 

4 n bars in a multicolor pattern 

4 n bars each in a solid color 

4 n bars in one of p multicolor 
patterns 
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Examples 
1. Plot four points in color 1: 

1 GGLINE 4% 2p400 400 400 600 600 600 600 400 
2. Plot three points in colors 1 2 and 1: 

1 2 1 DGLINE 3 2p400 400 600 600 800 800 

or 

1 2 DGLINE 3 2p400 400 600 600 800 800 

3. Draw the solid bar vith diagonal corners 400 400 and 600 
eno and color it with an alternating pattern of colors ! 


1 2 ÜGLINE 1 4p400 400 600 600 


4. Draw a box in color 3 connecting the four points plotted 
in the first example: 


A+ 1 5 2 p 400 400 400 600 600 600 600 400 400 400 
3 GLINE 4 

Error Reports 

DOMAIN ERROR The left argument contains an entry that 
is not a non-negative integer. 

LENGTH ERROR The right argument does not have either 
two or four columns 

RANK ERROR The rank of the right argument is not 2 


or 3, or the rank of the left argument 
is not 1 or 2, or there are four columns 
in a right argument of rank greater than 
25 


Copyright 1984 STSC, Inc. 3-136 System Functions 


et k P. rn D6MASK 


The monadic system function [GMASK determines which 
pixels, if any, are masked out pixels in lines drawn by 
DGLINE and [IGCIRCLE. 1t allows you to leave the background 
unchanged while drawing dotted or dashed lines, bars, and 
fill. 6MASK, as described here, is specific to the 
APL*PLUS/PC System; it may be different or absent in other 
APL*PLUS Systems. 


Syntax 
result - IGMASK bitpattern 
result - the previous “GMASK setting 
bitpettern - a bit vector of up to length 16 or an 
integer between 32768 and 32767 
corresponding to a bit vector of length 16 
Arguments 
The right argument of JGMASK_can be a bit vector of up 
to length 18, an integer betveen 732768 and 32767 that 
corresponds to a bit vector of length 16, or an empty 
vector. 
Result 


The result of IGMASK is the previous value of CGMASK. 


L&MASK-Dependent Primitive and System Functions 


No primitive functions depend upon the IGMASK setting. 
The setting affects the system functions CIRCLE and 
DGLINE. 


Effect 


DGMASK allows you to draw dotted or dashed lines or 
rectangles over existing images. When TGMASK is set, it 
causes only certain of the pixels to be colored over when 
lines are drawn or solid areas filled in using DGLINE or 
DGCIRCLE. The remaining points on the figure being drawn 
are not affected. 


The mask pattern for determining which points are 
colored and which are not t by the bit vector of shape 
16 corresponding to the right argument of CGLINE. This 
pattern is repeated as many times as necessary to fill the 
Object being drawn. Each 1 in this pattern corresponds to a 
point that is drawn, and each 0 corresponds to a point that 
is masked. When used with solid fill patterns produced by 
DGLINE, the mask vector is rotated 1 pixel to the left for 
each successive row. This produces dithered or diagonally 
Striped bars. 


The mask pattern can be magnified using DG200W. The 
Gefault value for SGMASK is ^1 (no mask). 
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The bit pattern corresponding to the bit vector BV can 
be computed as follows: 


21BVx 1,15p1 


1f the right argument of DGMASK is an empty vector, 


there is no effect; only the current DGMASK setting is 
returned. 


QG6MASK affects only the figure drawing functions OGLIWE 
and DGCIRCLE. 


Examples 


Sample values for the right argument of (GMASK: 


Bit pattern Value Effect 
1111111111111111 L1 solid lines (default) 
1010101010101010 721846 dotted lines 
1111111100000000 256 dashed lines 


Error Reports 


DOMAIN ERROR The argument is not a boolean vector or 
an integer singleton. 

LENGTE ERROR The argument has a length greater than 
16. 
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DGPAINT Color Bounded Areas IGPAINT 

The dyadic system function JGPAINT fills areas on the 
graphics easel that are outlined or bounded by a single 
Color with a specified color or pattern. See "Graphics 
Overview" in the User's Guide. PAINT, as described here, 
is specific to the APL*PLUS/PC System; it may be different 
or absent in other APL*PLUS Systems. 


Syntax 
fillcolor “GPAINT where 


fiilcolor - an integer or character singleton or vector 
representing the color or pattern to be 
painted 

where - a three-column vector or matrix of starting 
points and boundary colors 


ZGPAINT can be used to fill one or several areas with a 
solid color or pattern. The syntax for filling a single 
area is discussed below. 


The left argument is either an integer representing the 
color with which the single area is to be painted, or a 
character corresponding to a bit pattern to be used in 
coloring the area. If the left argument (fillcoler} is an 
integer that is negative or is larger than the number (N) of 
colors available, it is interpreted as representing the 
color corresponding to Nlfillcolor. 


The right argument is a vector of length 3. The first 
two entries of the vector are the coordinates of a point 
inside the area being filled. This point is the starting 
point. The third entry of the right argument specifies the 
color of the boundary. If it is positive or zero, the color 
represented by that number is the boundary color. If it is 
negative, the color represented by the absolute value of 
this number is the only color painted over (that is, all 
other colors are boundary colors). 


For filling several areas simultaneously. the left 
argument of [GPAINT is a vector or scalar and the right 
argument is a three-column matrix. The color choices in the 
dete argument are re-used cyclically until no more are 
needed. 


Result 


The function “GPAINT does not return an explicit 
result. 
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Effect 


This function is used to fill one or several areas of 
the screen with a solid color or color pattern. It is not 
affected by [JGTYPE. 


An area is defined as the interior of the smallest 
closed curve (sides may be straight or curved) having the 
following properties: 


1. It contains the seed point. 

2a. If the third entry of the right argument is 
non-negative, the color of its sides is either the 
color specified by the left argument (fill color) 
or the color specified by the third element of the 
right argument (boundary color). 

b. If the third entry of the right argument is 
negative, sides of the boundary are formed by 
pixels colored with any color other than that 
Specified by the absolute value of the third 
element of the right argument. 


In the case where the left argument is a character, the 
Character itself is not drawn, but the bit matrix that 
defines the character is used to produce the color pattern 
of the fill. 


The translation from character bit pattern to color 
fill pattern is done as follows. Each character for the 
graphics screen is defined by an 8 by 8 Boolean matrix. 
Each row of this eight-row bit matrix is interpreted as a 
color path for an eight-row tile. This tile is replicated 
by. GGPAINT to fill the area defined by its right argument. 
The graphics pattern produced by a particular row of the 
character matrix depends on the number of colors available 
on the graphics adapter. 


1f only two colors are available, each row yields a 
pattern of black and white dots corresponding to the 0s and 
is in the row, 


If four colors are available, then two bits are 
required to specify each color. So each pair of bits in the 
row of the character is used to specify the color of one 
tile pixel. Therefore, the first two bits define the color 
of the first tile pixel, the next two bytes define the color 
of the second pixel, and so on. For example, using palette 
0 of the IBM color board: 


Color Number Bi rn 
black o oo 
cyan 1 91 
magenta 2 10 
white 3 11 
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Suppose a row of the character definition matrix has 
value 54. This corresponds to the bit vector: 


00110110-4222222227 54 


The corresponding row of the tile pattern would have 
four pixels that would be colored: 


black white cyan magenta 


For graphics adapters using sixteen or more colors, the 
interpretation of the bit pattern is done in a similar way. 
In the case of sixteen colors, each row of the character 
matrix defines only two tile pixels since it takes four bits 
to represent sixteen different colors. The use of 
characters to produce color patterns is illustrated by 
Example 2 in "LG6SBADE -- Color Rectangular Areas Colors or 
Patterns". 


Note that since the current implementation supports 
only 255 colors (and black). if the third entry of the right 
argument of “iGPAINT is 256, it is treated as if it is 
negative as well as 0, This means that every color except 
black is considered a boundary color. 

JGPAINT can be used to paint several areas 
simultaneously. This is done by using an n-by-3 matrix as 
the right argument. In this case, the areas specified by 


each row of the right argument are filled with the 
corresponding element of the left argument. 


Examples 
1. Draw a circle in color 1 and fill it with color 2: 


CIRCLE $00 500 100 o 2 DGPAINT 500 500 1 


2. Using the picture drawn in Example 1, draw another 
circle to illustrate the effect of using a negative 
integer for the last element of the right argument of 
DGPAINT: 


3 CGCIRCLE ^00 400 100 © 0 jGPAINT 500 500 2 


Error Reports 

DOMAIN ERROR Either the left argument or the third 
column of the right argument contains a 
non-integer entry. 

LENGTH ERROR The right argument does not have three 


columns. 
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RANK ERROR The left argument has rank greater than 
1 or the right argument has rank greater 
than 3. 
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IEPRINT -- Graphics Display to Printer DepRINT 


The dyadic system function [PRINT prints the contents 
of the graphics viewport on the screen sideways on an EPSON 
or IBM dot-matrix printer vith appropriate graphics printing 
capability. See "Graphics Overview" in the User‘ e. 
ÜGPRINT, as described here, is specific to the APL«PLUS/PC 
System; it may be different or absent in other APL*PLUS 
Systens. 


Syntax 
shading [¢PRINT stretchout 


shading - a vector of one character for each color 
available 
Stretchout - a two- or three-element integer vector 
Argumen 


The left argument is a character vector with one 
character for each color available (1+[¢sTATUS) The 
characters represent elements of the graphics V, and are 
used as bit patterns with which to create shadings for each 
color on the printer. 


The right argument is an integer vector with two or 
three elements, representing, in order: 


[1] the vertical zoom factor to be used 

[2] the horizontal zoom factor to be used 

13] optional selection of parallel printer port 
(defaults to 1 for LPT1). 


Effect 


The image in the graphics viewport is copied to the 
printer. Each color is represented by a shading produced 
using the bit pattern of the graphics CAV character 
Corresponding to the matching element of the left argument. 
For a four-color graphics display, the set 


ZAV[255 219 176 1789[I0) 


provides shadings appearing as white, two shades of grey. 
and black. Used in the order shown here as a left argument, 
the image appears as black on white. If the order is 
reversed in the left argument, the image appears as white on 
black. Experimentation aids personal selection. 


The zoom factors in the right argument select the 
number of printer pixels used in that direction to represent 
each pixel in the viewport. The pixel resolution on the 
printer is 960 pixels for an 80-character vidth, which 
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represents the vertical resolution on the screen because the 
image is printed with a ninety-degree rotation from the 
original screen image. To achieve approximately the same 
aspect (proportion of horizontal to vertical distances) as 
on the screen, you must specify approximately 750 pixels 
down the printed page. Thus, zoom factors of 4 2 
approximate the aspect on a Screen used at a resolution of 
320 by 200 (like the IBM when used with four colors). These 
zoom factors both adjust the aspect and spread the image to 
about 0.8 of the normal 80-character vidth. 


Alternatively, you can have the image printed in the 
same orientation as the screen (that is, not rotated 90 
degrees) by doing a 1 POKE 234. 


Examples 


Da4vt255s 219«DIO) DGPRINT 2 1 
(Prints black on white with tvo-color 
resolution of 720 by 350, like Hercules 
or Orchid adapters.) 


[4Y[06179*116] [JGPRINT 2 2 2 
(Prints on printer 2 in 16 shadings from 
a 16-color 320 by 500 resolution 


adapter.) 

Error Reports 

DOMAIN ERROR The left argument is not 
character-valued, or the right argument 
is not integer-valued. 

LENGTH ERROR The left argument does not have an 
element for each color available, or the 
right argument is not of length 2 or 3. 

RANK ERROR One argument is not a vector. 
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C@s#aDE -- Color Rectangular Areas Colors CGSHADE 
or Patterns 


The dyadic system function [@S#ADE fills specified 
rectangles on the graphics easel with solid colors or 


bit-specified patterns. See "Graphics Overview" in the 
Us: Guide. (GSHADE, as described here, is specific to 


the APL*PLUS/PC System; it may be different or absent in 
other APL«PLUS Systems. 


Syntax 
fillcolor “GS#ADE corners 


fillcolor - an integer or character singleton or vector 
corner: - à four-element vector or four-column matrix 


Arguments 


The right argument is a four-element vector or a 
four-column matrix. Each row of the right argument defines 
two diagonal corners of the rectangular area to be filled. 
The first two columns are the X and the Y coordinates of one 
corner point, while the last two columns are the coordinates 
of the corner point diagonally opposite the first in a 
unique rectangle. In the degenerate case, only a line 
Segment is formed. 


filled with solid colors. When this integer (fillcolor) is 
negative or greater than the number (N) of colors available, 
the rectangle is filled vith the color corresponding to 
N|fillcolor . f the left argument is character, the bit 
patterns used to define the characters provide the color 
patterns for filling the areas. 


If the left argument is integer, the rectangles are e 


The color choices in the left argument are re-used 
cyclically until no more are needed. 


Result 

The function J¢S#ADE returns no explicit result. 
Effect 

CGSHADE is used to fill rectangular areas with either 
solid colors or patterns. If the left argument is integer, 
the fill is in the colors specified. 1f the left argument 
is character, the fill ís made from the bit patterns used to 
draw the characters. 


Characters used as left arguments of “I¢SHADE do not 
appear as the fill of the rectangle colored by “iGSHADE. 


Instead, the bit matrix that defines the character is used 
to produce the color pattern of the fill (see also 
"CGPAINT -- Color Bounded Areas"). 
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The translation from character bit pattern to color 
fill pattern is done as follows. Each character for the 
graphics screen is defined as an 8 by 8 Boolean matrix. 
Each row of this eight-row bit matrix is interpreted as a 
color path for an eight-row tile. ‘This tile is replicated 
by DGSBADE to fill the area defined by its right argument. 
The graphics pattern produced by a particular row of the 
Character matrix depends on the number of colors available 
on the graphics adapter. 


If only two colors are available, each row yields a 
pattern of black and white dots corresponding to the Os and 
1s in the rov. 


If four colors are available, two bits are required to 
specify each color. So each pair of bits in the row of the 
character is used to specify the color of one tile pixel. 
Therefore, the first two bits define the color of the first 
tile pixel, the next two bits define the color of the second 
pixel, and so on. For example, using palette 0 of the IBM 
color board: 


Color Number Bit pattern 
black o 00 
cyan i 01 
magenta 2 10 
white 3 11 


Suppose a row of the character definition matrix has 
value 54. This corresponds to the bit vector: 


0011012104222222227 58 


The corresponding row of the tile pattern would have 
four pixels that would be colored: 


black white cyan magenta 


For graphics adapters using sixteen or more colors, the 
interpretation of the bit pattern is done in a similar way. 
In the case of sixteen colors, each row of the character 
matrix defines only two tile pixels since it takes four bits 
to represent sixteen different colors. 


DCMASK, ÜGTYPE, and [J6200M do not alter the bit 
patterns used to fill rectangles with [i¢SHADE. The areas 
covered using [GS#ADE mix with the existing screen image 
according to the current setting of DGTYPE. 


Copyright 1983 STSC, Inc. 3-146 System Functions 


Examples 


1. Draw a solid bar in color 1 with diagonally opposite 
Corners located at 100 100 and 200 200. 


1 CGSHADE 100 100 200 200 @ 


2. LDA4V[177*DIO] is the half-tone shaded block. The first, 
third, fifth, and seventh rows have pixel pattern 


01010101 


and the second, fourth, sixth, and eighth rows have bit 
pattern 


10101010 
If your adapter has a four-color display, then 
D4AYL17?«DI0] DGSEADE 300 300 400 400 
will produce a rectangle colored with alternate stripes 
of color 1 (bit pattern 0 1) and color 2 (bit pattern 1 
o0. 
If your adapter has sixteen Colors, this will produce a 
rectangle with alternate stripes in color 5 (bit pattern 
0 10 1) and color 10 (bit pattern 1 0 1 0). 


3. DGSEADE can clear the screen without resetting defaults e 
as (GINIT would: 


0 OGSHADE 0 O 1023 1023 


Error Reports 

DOMAIN ERROR The left argument contains a non-integer 
entry. 

LENGTH ERROR The right argument does not have four 
columns. 

RANK ERROR The right argument is not a four-element 


vector or a four-column matrix. 
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EST ATU. 


hi Oesrarus 

The niladic system function D¢sTaTus returns the 
current status of the graphics display parameters. 
ÜGSTATUS, as described here, is specific to the APL*PLUS/PC 
System; it may be different or absent in other APL*PLUS 
Systems. 
Syntax 

result + OGSTATUS 

result - an integer vector of length 4 

Result 


The result of [¢STATUS is a four-element numeric vector 
specifying the following: 


JeSTATUS[1) - number of colors available 
Oesratus(2] - horizontal resolution 
DGSTATUSL3] - vertical resolution 


DGSTATUSI^] - base segment address for start of 
graphics memory 


TION: User-defined functions should not depend on 
the result of [JGSTATUS being a four-element vector, since 
more elements may be appended to the result in future 
releases of this system. 


Example 
0 DGINIT 'IBMCOLOR’ 
IBMCOLOR 


QcsrATUS 
4 320 200 718532 
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DETYPE -- Type of Interaction with Previous Pixels OsryPr 


The monadic system function JGTYPE selects or reports 
the type of interaction with which new pixels overwrite 
existing pixels in the graphics display. [GTYPE, as 
described here, is specific to the APL*PLUS/PC System; it 
may be different or absent in other APL*PLUS Systems. 


Syntax 
result + “CTYPE type 
result - the previous setting of “GTYPE 


type - an integer singleton between 0 and 3, or an 
empty vector 


Arguments 


The right argument of “GTYPE is an empty vector or an 
integer between 0 and 3 that corresponds to the manner in 
which neviy órawn pixels vill mix with existing pixels. 


Result 


The result of "GTYPE is the integer corresponding to 
the previous “GTYPE setting. 


-EIYPE-Dependent Primitive and System Functions 


No primitive functions depend upon the CóTYPE setting. 
The setting affects the system functions CGCIRCLE, GLINE. 
and “GWRITE. 


Effect 


If the right argument of -6TYPE is an empty vector, 
there is no effect (only the current [GTYPE setting is 
returned), If the right argument of LGTYPE is 0, i, 2, or 
3. the effect is described in the table below: 


Type Effect 


o New colors replace old colors (SET, the default 
type) 

1 New colors mix with old colors (OR) 

2 Colors in common cancel; other colors mix (XOR) 

3 Colors in common cancel: other colors ignored 
(RESET) 


Colors are the presence or absence of each possible 
element of color at any given pixel. For example, yellow is 
a mix of red and green. Yellow, therefore, has red in 
common with the color red. 

Example 


TGTYPE 3 
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Error Reports 


DOMAIN ERROR The right argument is not an integer 
between 0 and 3. 


LENGTH ERROR The right argument is not a singleton. 


Copyright 1983 STSC, Inc. 3-150 System Functions 


DGVIEM -- Select Viewport for Next Drawing DevrEw 


The monadic system function (IGCVIEW selects the 
rectangular area of the screen onto which additional 
graphics displays are projected. See "Graphics Overview" in 
the User's Guide. [¢VIEW, as described here, is specific to 


the APL«PLUS/PC System; it may be different or absent in 
other APL*PLUS Systems. 


Syntax 


result + IGVIEW viewport 


result - the previous CGVIEW setting 
viewport - a four-element integer vector with values from 
© through 1023, or an empty vector 


Argument 


The right argument specifies the new vievport as two 
successive pairs of X and Y coordinates representing two 
diagonally opposite corners. The viewport is the portion of 
the screen onto which further graphics displays of portions 
of the easel visible in the easel window ( GWINDOW) will be 
projected.  '6VIEW treats the entire screen as scaled from 
(0,0) at the upper-left corner to (1023,1023) in the 
lower-right corner. 


Result 
The result of OGYIEW is the previous UGVIEW setting. 


ZGVIEF-Dependent P. 


No primitive functions depend upon the JGVIEW setting. 
The setting interacts with the setting of the system 
function —iGWINDOW. 
Effect 


ÜGVIEV allows you to select the portion of the screen 
in which the graphics display is drawn. 


1f the right argument is an empty vector, there is no 
change in the position in which displays are drawn; only the 
current [IGVJEW setting is returned. 


[VIEW affects only images drawn after it is set. It 
will not affect current displays. 


The default setting for JGVIEW is 0 0 1023 1023. 
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Exemples 


1. To display graphics images in the upper-left quarter of 
the screen, use: 


o OGVIEW O O 512 512 


2. ŪGVIEW can be used to correct distortion that occurs 
when a square easel is projected onto a rectangular 
Screen. 


For example, in the case of a monitor display that is 24 
by 18 cm (12 inch diagonal), the ratio of height to 
width for this screen is 0.75. To correct the resulting 
distortion, select an area that has its horizontal 
dimension 0.75 as large as its vertical dimension. 
Since the entire screen width is considered (for IGVIEW ) 
to be 1023, the area has a width 767 (1023 x 0.75). 
Therefore, setting ŪGVIEW 0 0 76? 1023 eliminates the 
distortion caused by unequal scaling in horizontal and 
vertical directions. This viewport selection uses only 
three quarters of the screen. 


Error Reports 


DOMAIN ERROR The entries of the right argument are 
not all integers between 0 and 1023. 
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[IceWINDOW -- Select Portion of Easel for 


splay  GWINDOW 


The monadic system function [WINDOW selects the 
portion of the graphics easel to project onto the viewport 
on the screen for subsequent graphics display. It can 
magnify portions of images and can change the origin and 
orientation. See "Graphics Overview" in the User's Guide. 
DGWINDOW, as described here, is specific to the APL*PLUS/PC 
System; it may be different or absent in other APL*PLUS 
Systems. 


- the previous (WINDOW setting 
Corners - an integer vector of length à vith entries 
between 0 and 1023, or an empty vector 


The integers in the right argument of “iGWINDOW 
represent the X and Y coordinates of two diagonally opposite 
corners of the rectangular section of the easel that is to 
be viewed. 


Resuit 


The result of “GWINDOW_is the integer vector of length 
4 representing the current LGWINDOW setting. 


UghINDOW-Dependent Primitive and System Functions 


No primitive functions depend upon the “iGWINDOW 
setting. The setting interacts with the setting of the 
system function | GVIEV. 


Effect 


DGWINDOW allows you to select the portion of the easel 
that vill be displayed. 


If the right argument is an empty vector, there is no 
Change in the portion of the easel being displayed (only the 
current (GWINDOW settings are returned). 


The first two elements of the right argument of 
COWINDOW are the coordinates of the origin of the portion of 
the easel to be displayed. The last two elements of the 
right argument are the coordinates of the diagonally 
opposite corner (terminus). In subsequent uses of the 
graphics drawing functions. only those portions within the 
Specified area vill be displayed. [WINDOW will not affect 
current displays. 


IGWINDOW can be used to magnify graphics displays by 


projecting the contents of a small portion of the easel onto 
a large portion of the screen. 
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DJ&WINDOW can also be used to move the screen origin and 
change the direction of increasing X or Y coordinates. The 
first two entries of the right argument of [GWINDOW specify 
the location of the origin. 


The third entry specifies the X coordinate of the 
terminus of the easel. If the difference between the third 
entry and the X coordinate of the origin is positive, the 
direction of increasing X values is from left to right. If 
the difference is negative, the direction of increasing X 
values is from right to left. 


The fourth entry of the right argument is the Y 
coordinate of the terminus of the easel. If the difference 
between the fourth entry and the Y coordinate of the origin 
is positive, the direction of increasing Y values is from 
top to bottom. If this difference is negative, the 
direction of increasing Y values is from bottom to top. 


One interesting use of DGWINDOW is to change the 
direction of increasing Y values and move the easel origin 
to the lower-left corner of the screen to make the screen 
look like the first quadrant of a standará Cartesian 
coordinate system (see Example 4, below), 


Examples 


1. To display only those portions of graphics drawings in 
the upper-left corner of the easel, set: 


CGWINDOW O O 511 511 


2. To see how 
graphics wi 


WINDOW can magnify an object, initialize 
h CGINIT and then do the following: 


A * 1 5 2p100 100 100 200 200 200 200 100 © 1 CGLINE A 
UGWINDOW O © 511 511 9 3 (]GLINE 4 


The first line defines the array 4 that vill be used in 
drawing a box and draws the box with the default setting 
(Q6WINDOV O 0 1023 1023). The second line resets the 
window and draws the same box again. This time the box 
appears tvice as big and is moved toward the center of 
the screen. 


The appearance of the box changes: with only a quarter 
of the easel now being projected onto the same size 
viewport, the box occupies four times its previous area 
(each side is twice as long). The distance from the 
left edge of the screen to the left edge of the box is 
Still 100 units. (Before we reset [GWINDOW, it was 0.1 
(100*1024) of the screen's span; after resetting 
ÜGWINDOW, it is 0.2 (1005512) of the screen's span.) 
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3. TGWINDOW can be used to make the resolution of the easel 
equal to the actual resolution of the display adapter. 
In this way. the horizontal and vertical distances 
(measured in pixels) between points is exactly the same 
on the screen as the difference between the X and Y 
coordinates of the points. Suppose the resolution of 
the graphics screen is 640 200, then: 


ZGWINDOW 0 O 639 199 


will produce a easel with the same resolution as the 
display adapter. 


WINDOW can be used to change the location of the 
origin and change the direction of increasing Y values 
to make the screen coordinates like the coordinates for 
the first quadrant of a standard Cartesian coordinate 
system. This is accomplished by setting: 


TGWINDOW 0 1023 1023 0 


Here the origin is 0 1023 (the lower-left corner). The 
direction of increasing X values is to the right since 
1023-0 is positive. The direction of increasing Y is 
from bottom to top since 0-1023 is negative. The 
terminus of the screen is 1023 0 (the upper-right 
corner). 


Error Reports 
DOMAIN ERROR The right argument is not composed 
entirely of integers between 0 and 1023, 


or the argument describes a degenerate 
rectangle with no area. 
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OgwRITE -- Write Text on Graphics Screen DGWRITE 


The dyadic system function CGWRITE draws characters on 
the graphics screen. See "Graphics Overview" in the 
User's Guide. [J¢WkITE, as described here, is specific to 
the APL*PLUS/PC System; it may be different or absent in 
other APL*PLUS Systems. 


Syntax 
text DGWRITE xyc 


text - a character array 
Xyc - an integer vector of length 3 


Arguments 


The left argument is a character array that is to be 
displayed on the graphics screen. 


The right argument is an integer vector of length 3. 
The first two elements define the location of the upper-left 
corner of the display, and the third element specifies the 
color in which the text is to be drawn, 


When OGZ0OM is set to 1, the individual characters fill 
an eight-pixel square area on the monitor screen. It should 
be noted that the size of the rectangle covered by each 
characters when measured on the easel, is generally not 8 by 
@ pixels. 


For example, if your adapter is set for a 320 by 200 
pixel display, then each 3.2 (10234320) virtual pixels 
Corresponds to one pixel on the screen in the horizontal 
direction, and each 5.12 (1023+200) virtual pixels 
So responds to one pixel on the screen in the vertical 
direction. This means that with OGVIEW and DGWINDOW set at 
0 0 1023 1023 (default settings), each character fills a 
rectangle on the easel having dimensions approximately 26 by 
41 (2628x10234320 and 41-8x1023t200). 


ÜGZ00M can be used to enlarge the size of characters. 
DcTYPE affects the way characters are combined with the 
existing picture. 


Example 
"MONTHLY REPORT' DGWRITE 400 100 2 
Error Reports 
DOMAIN ERROR The entries of the right argument 


are not integers or are greater 
than 32757, or the left argument is 
not a character array. 
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LENGTH ERROR The right argument is not of length 
3. 


RANK ERROR The right argument is not a vector. 
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D6Z00M -- Magnify Characters and Dot Patterns D6z00M 


The monadic system function []6200M selects or reports 
the size to be used for drawing letters with DGWRITE and the 
repetion factor for pixel use in color paths by DGCIRCLE and 
DGLINE. See "Graphics Overview" in the User's Guide. 
D6200M, as described here, is specific to the APLxPLUS/PC 
System; it may be different or absent in other APL*PLUS 
Systems. 


Syntax 
result + O6200M n 


result - the value of the previous (¢Z00M factor 
n - a non-negative integer or an empty vector 


Argument 


The right argument is either a non-negative integer 
specifying the amount of magnification, or an empty vector. 


esult 


The result of /)6200M is the previous value of []6G200M. 
The defauit value of j6200M is 1. 


D&Z09M-Dependent Primitive and System Functions 
No primitive functions depend upon the [1¢Z00M setting. 


The setting affects the system functions J¢CIRCLE, D6LINE, 
and DGERITE. 


Effect 


If the right argument of j]6200M is an empty vector, 
there is no effect: only the current []6200M setting is 
returned. 


If the right argument of JGZ00M is a positive integer, 
certain bit patterns are magnified by the amount specified 
by the right argument. The manner in vhich this works is 
Gescribed in detail below: 


* (¢z00m affects characters written with DGWRITE by 
magnifying them according to its right argument. 


* [6200M affects the bit pattern used in drawing lines 
(OGLINE and [GCIRCLE) and filling solid figures 
G)GLINE) by replicating each pixel according to the 
value of the right argument of ÜGZOOM. Thus, the 
pattern formed by: 


DezooM 2 o 3 2 2 DGLINE 1 2 200 0 100 100 
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is a repeating pattern of two pixels of color 3 
folowed by four pixels of color 2. 


e DGZ00M also affects the patterns masked with (J¢MASK 
by replicating each displayed or masked pixel 
according to the number specified by its right 
argument. 


e [6200M does not affect characters or patterns 
already drawn. 


Example 


D6200M 4 
1 


Error Reports 


DOMAIN ERROR The right argument of [10200M is not a 
positive integer. 


LENGTH ERROR The right argument of L6200M is not à 
singleton. 
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HELP -- Help on a Named Topic DEESLP 


The monadic system function (#ELP activates the HELP 
facility. The HELP facility displays information on the 
topics available in the HELP files in use. [#ELP, as 
described here. is specific to the APL*PLUS/PC System; it 
may be different or absent in other APL*PLUS Systems. 


For a general discussion of using the HELP facility, 
see "The HELP Facility" in the User's Guide. See "Building 
Custom HELP Files" in the Programmer's Manual for 
information on building custom HELP files and details on the 
internal workings of the HELP facility. Also see ")#ELP -- 
Online Documentation" in the Programmer's Manual, which 
presents the differences between using [HELP and )RELP. 


Syntax 


DEELP topic 


topic - a quoted or stored character vector or singleton 
representing the topic 


Argynent 


If the argument to [HELP is a topic on which 
information is available, the system displays it without 
further user input. Topics containing a []TCNL character are 
truncated at that point; therefore, [HELP ODM vill look only 
for the first line of the diagnostic message. Topics longer 
than 80 characters are truncated. 


An empty vector (“HELP '') argument is equivalent to 
OFELP DNSTOPIC. If the topic is not in the list of HELP 
topics, the system may display a menu of choices for user 
selection from the directory of the first HELP file found of 
those listed in DENAMES. 


Result 
DKELP does not return an explicit result. 
Effect 


Once you enter the HELP facility, the system's 
interaction with you is the same as if HELP were entered 
with the system command )#ZLP, When there is too much 
information to display at once, the information is stored, 
and the system pauses for user input before presenting the 
next screen. 


DsELP ** (No topic is specified. A 
menu of choices is 
presented on the screen.) 
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DHELP DDM (Information about the 
error message now stored 
in GDM is displayed.) 


DELX + 'UDM o ORELP ODM’ (Automatically produces 
the above information 
after every error 


message.) 
Error Reports 
DOMAIN ERROR The argument is not character-valued. 
RANK ERROR The argument is not a vector or singleton. 


If an error occurs during the execution of "\ELP, JELX 
is not executed. Instead, a HELP panel indicating the type 
of error displays, and you are invited to enter another 
choice of topic or to simply press Enter to conclude the 
HELP session. 


Copyright 1983 STSC, Inc. 3-161 System Functions 


JENAMES -- HELP Files to be Used DENAMES 


The workspace-related system variable [NAMES is the 
ordered list of disk files to be used by the HELP facility. 
GHNA4MES is experimental in this release of the APL*PLUS/PC 
System; it may be different, absent, or replaced by an 
entirely different feature in a subsequent release. 


Donain 


The domain for assignment to [ENAMES is a 22-character- 
vide matrix of up to ten rows, or a 22-character vector. 
The position of a file identification vithin the vector form 
is unimportant for assignment. 


Value when Referenced 
When DENANMES is referenced, its value is a 22-column 


character matrix containing one file identification in each 
rov. 


Default Valve in a Clear Workspace 


In a clear workspace, the default value of CHNAMES is a 
one-row matrix containing the name of the APL*PLUS/PC 
System's HELP file, SYSHELP. 


DRHAMES-Dependent Primitive and System Functions 


No primitive functions depend upon the value of 
DENAMES. The HELP key, )#ELP, and [HELP depend on the value 
of DENAMES. 


Effect 


Any call to the HELP facility searches through the 
files specified in LENAMES, in order, until it finds the 
requested item or runs out of files to search. Files listed 
in DENAMES but not found are ignored, and the system 
Continues the search through the list. 


For a general discussion of the HELP facility, see the 
User's Guide; for details of the inner workings, see 
"Building Custom HELP Files" in the Programmer's Manual. 
Examples 

DERAMES 

1 CASEFLOW 
O SYSHELP 

LENAMES + ( 22 + '1 MYEINTS' ),[1] DENAMES 

Error Reports 


DOMAIN ERROR The value being assigned to DENAMES is not 
character data. 
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LENGTH ERROR The value being assigned to LANAMES is not 


22 columns vide, or has more than 10 rows. 


RANK ERROR The value being assigned to "NAMES is not 


a matrix or vector. 


WS FULL There is not enough room in the workspace e 
to display the value of JENAMES. 
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[HETOPIC -- Default Topic to be Used by the DEgTOPIC 
HELP Facility 


The workspace-related system variable [ATOPIC is the 
topic to be searched for vhen the HELP facility is activated 
with no other topic specified. DETOPIC is experimental in 
this release of the APL*PLUS/PC System; it may be different, 
absent, or replaced by an entirely different feature in a 
subsequent release. 


Domain 


The domain for assignment to JETOPIC is a character 
vector or singleton. The assignment truncates, however, 
after 80 characters or just before the first nevline 
character (DTCNL). 


Value when Referenced 


When DETOPIC is referenced, its value is a character 
vector of up to 80 characters with no embedded newline 
characters, 


Default Value in a Clear Workspace 


In a clear workspace, the default value of [#TOPIC is 
an empty character vector, 


DETOPIC-Dependent Primitive and System Functions 


No primitive functions depend upon the value of 
DETOPIC. The value of [TOPIC is used in connection with 
the Help key, with )#ELP when no topic has been specified, 
and when J#ELP is used with an empty argument, 


Effect 


Any call to the HELP facility which did not specify a 
topic to be searched for and explained, causes a search 
through the active HELP files (those specified in DWNAMES), 
in order, until it finds information on the topic named in 
ÜSTOPIC or runs out of files to search. 


DNTOPIC allows user applications to incorporate the 
Help key as an integral part of the application. The 
judicious use of DETOPIC can cause the Help key to jump 
directly to the topic or menu the programmer deems 
appropriate at any given point during the application. An 
example would be providing help on exactly what kind of 
information is needed in answer to the current prompt. 


xampl. 
DETOPIC + ‘INPUT FIELD 1' © [CURSOR + STARTFIELD1 


DHTOPIC + ‘GENERAL DIRECTIONS" 
SAVE 
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Error Reports 


DOMAIN ERROR The value being assigned to [ATOPIC is not 
character data. 


RANK ERROR The value being assigned to [#TOPIC is not 
a vector or singleton. 
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PLIST Identifier st DIDLIST 


The system function [IIDLIST has both monadic and dyadic 
forms. 


The monadic form of [IIDLI$T returns a character matrix 
of identifiers (names). 


The dyadic form of [IDLIST returns a character matrix 
of identifiers (names) that begin vith designated letters. 


The most local definition of an identifier is 
referenced. Functions, variables, groups, and labels are 
Selected according to the value of the right argument. 


result + LIDLIST integer 
result + character [IDLIST integer 


result ^ - the explicit result 
integer - an integer singleton 
character - a character value 


The right argument is an integer-valued singleton that 
determines the classification of identifiers to be produced. 
The argument is the sum of one or more of these values: 


Value Identifiers 

o Empty 

1 Functions 

2 Variables 

8 — Labels 
To obtain a combination of identifier types, the sum of the 
appropriate values is used. When the right argument is 
negative or greater than 15, the result is the same as that 
produced by substituting 16 residue of the right argument. 


The left argument is a scalar or vector of alphabetic 
Characters that restricts the names produced to those whose 
first letter occurs somewhere in the argument. The left 
argument is optional. 

Result 


The explicit result of [IDLIST is a character matrix of 
identifiers. The rows are in alphabetic order. 


Example 
pÜe-'TUY* DIDLIST 1 


TRI 
15 
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Error Reports 


DOMAIN ERROR The right argument has the proper 
rank and length but is not integer 
valued; or for the dyadic form, the 
left argument is not character 
valued, or it contains non- 
alphabetic characters. 


LENGTE ERROR The right argument does not have 
exactly one element. 

WS FULL The explicit result requires more 
workspace storage than is 
available. 

omparison IDLI$T with OWL 


CIDLIST and DNL provide similar capabilities. The 
differences are listed below. 


e ZIDLIST accepts an argument consistent with the 
result of LIDLOC; DNL accepts an argument consistent 
with the result of DNC. 


e [DIDLIST and CYL use different classification codes. 
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HDLOC -- Identifier Localization Orpioc 


The monadic system function [IDLOC returns the local 
and global classifications of a list of identifiers (names). 


Syntax 
result + [JIDLOC idlist 


result - the explicit result 
idlist - a list of identifiers 


Argument 


The argument contains a list of zero or more 
identifiers in one of the following forms: 


* a character scalar or vector containing one 
identifier 


* a character vector containing two or more 
identifiers, with each pair separated by one or more 
blanks 


e a character matrix with one identifier in each row. 
Result 


The explicit result of DIDLOC is a numeric matrix with 
each row corresponding to an identifier named in the 
argument. The matrix has one column for each function call 
in the state indicator, progressing from most local to most 
global in increasing column order. The last column contains 
the global definitions. 


Values that may be returned are shown in the table 
below, The values in the last column are always non- 
negative. 


Value Classification 
7a Not localized at this level 
9 Localized with no assigned value at this 
level, or globally undefined 


1 System or user-defined function 
2 System or user-defined variable with value 
8 Label 
Example 
)MIV 
TRI[2]* N A 


2 
DIDLOC 'A N TRI" 
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Error Reports 


DOMAIN ERROR The argument has the proper rank 


but is not character valued; or it 
contains invalid identifiers. 


RANK ERROR The argument is not a matrix, 


vector, or scalar. 


WS FULL The explicit result requires more 


Compari 


workspace storage than is 
available. 


n of GIDLOC with “NC 


DIDLOC and LNC in this manual provide similar 


capabilities. The differences are listed below: 


* LIDLOC returns all local and global classifications; 
TNC returns only the locally active classifications 
of the identifiers. 


e [QIDLOC is more informative than INC. Different 
numeric codes are used by each; (WC returns a less 
specific classification code. 


* JIDLOC accepts a list of several identifiers 
represented as either a character matrix or a 
character vector: DNC accepts a list of several 
identifiers represented only as a character matrix. 


* DIDLOC returns a result consistent with DIDLIST:; [INC 
returns a result consistent with WL. 


* [NC accepts an ill-formed identifier name; (JIDLOC 
produces a DOMAIN ERROR. 
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IN Specifying the Input Source DIN 


The monadic system function [IN specifies the input 
source for further input to the APL session. DIN, as 
described here, is specific to the APL*PLUS/PC Syste: 
may be different or absent in other APL*PLUS Systems. 


it 


Syntax 
result + DIN 'source* 


result - the explicit result 
source - a character vector or singleton describing the 
input source to use 


Argument 


The argument to [IN is a character Singleton or vector 
that specifies the input source to use. Superfluous blanks 
are ignored. The argument can take one of three possible 
forms: 


Cry *D' Specifies a terminal input source. 
DIN 'filesource* Specifies a file input source. 
Orv '* Specifies no input source. 


The form of a file source specification (filesource) is 
as follows: 


'fileid :passnumber /component* 


Where :passnumber is an optional passnumber granting read 
access to the specified file, and /component (also optional) 
specifies which component of the file is to be read first. 


Result 


The explicit result of DIN is an integer scalar that 
indicates the success of the input specification or its 
reason for failure. If the result is anything other than 1, 
the input state has not been changed by (QIN. 


Result Meaning 
1 Specified input source established successfully. 
2 Unable to interpret specification. 
3 Ill-formed passnumber. 
10 FILE NOT FOUND. 
1i FILE TIED (with [NTIE). 
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12 FILE ACCESS ERROR (user account number in use 
does not have read access, or the wrong 
passnumber has been specified). 


13 FILE DAMAGED, 

25 FILE TIE QUOTA EXCEEDED. 

27 DRIVE NOT READY, 

28 DISK ERROR. 

32 LIBRARY NOT FOUND. 

33 INSUFFICIENT HANDLES. 
Effect 


The effect of CIN is to establish the input source to 
use, starting with the next request for input. This input 
Source can be used for the remainder of the APL session, 
even surviving the loading of another workspace. Possible 
input sources are the keyboard or a component file (such as 
a file produced by CAP) that has one line of input per 
component. 


Two special numeric scalar values can be used as 
components of a file input source: 


o ignore this component and use the next one 


2 exit (revert to keyboard input, default GIOSTATE, 
empty .51, default window). 


Note that a strong interrupt (using BREAK or Exit) will 
cause a reversion to keyboard input. 


Examples 

fs t No input source; the task 
cannot read input. 

DIN "7 Keyboard input source; 
the normal input state. 

DIN 'DRIVER' File input source in the 
default library; input to 
begin at the first 
component of the file. 

LIN 'i WSD0C:1010/25" File input source in 


library 1; file 
passnumber is 1010; input 
to begin at component 25. 
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Error Reports 


DOMAIN ERROR The argument is of proper rank but is 
not character-valued. 


RANK ERROR The argument is not a singleton or 
vector. 
WS FULL The explicit result requires more 


workspace storage than is available. 


The following errors may occur while using a file input 
source, and result in the diagnostic message being vritten 
to the output sink in use but not being recorded in DD 
DELX is not executed; any capture sink in use is switched 
off, but any file output sink remains in effect; input 
reverts to the keyboard and, if it was off, output to screen 
resumes. 


IW DATA ERROR (CMP n) Component n of file input source is 
unacceptable as input because it is 
numeric but not one of the tvo 
acceptable numeric scalar values (0 
for "bypass this component" or 2 
for "revert to keyboard input 
source"), exceeds maximum input 
length of 511 characters, or is not 
a scalar or vector. 


JIN DISK ERROR A disk error was encountered while 
trying to read the next component 
of the input file, probably due to 
8 hardware fault or to an 
unformatted or defective disk. 


ÜIN DRIVE NOT READY The disk drive containing the input 
file is not ready for use. 


LIN FILE DAMAGED The input file has invalid values 
in its component directory, 
possibly from having replaced the 
disk while the file was tied. 


QIN FILE DATA ERROR The input file component contains 
an improper (non-APL) value written 
by a non-APL program. 


DIN FILE INDEX ERROR A non-existent component has been 
referenced, typically by reaching 
the end of the input file. 


DIN FILE TIE ERROR The input source file has been 
erased from DOS using CMD. 
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JIN NO SOURCE ERROR Input is needed and no input source 
is in effect. 


DIN OPEN QUOTE ERROR The input file component contains 
unmatched quotes in an executable 
portion. 


Side effects from other errors or interrupts: input reverts 
to the keyboard, and screen output is added to any output or 
capture sinks in effect, if a file input source is exhausted 
or if the system encounters: a strong interrupt; an 
untrapped error (including system command errors); a trapped 
error where [ELI cannot be executed: a trapped error where 
DELY does not restart execution by a branch or by executing 
DERROR; or a weak interrupt where [ALI cannot be executed, 
or where the execution of []ALX does not restart the 
interrupted execution. 


Copyright 1983 STSC, Inc. 3-172.1 System Functions 


[INBUF -- Insert into Type-ahead Buffer DINBUF 


The ambivalent system function [INBUF empties and/or 
adds to the contents of the type-ahead buffer. [JINBUF is 
experimental in this release of the APL*PLUS/PC System; it 
may be different, absent, or replaced by an entirely 
different feature in a subsequent release. 


Syntax 


DINBUF keystrokes 
style DINBUF keystrokes 


style - àn integer representing position and action 
keystrokes - a vector of keystrokes to insert in buffer 


Arguments 


The optional left argument to LINBUF is an integer 
valued between ^1 and 1 inclusive, interpreted as follows: 


1 - insert before the current contents of the buffer 
(the defavlt) 
.9 - replace the current contents of the buffer 
1 - insert after the current contents of the buffer 


The right argument to JINBUF is a vector of keystrokes 
to place in the type-ahead buffer. The vector can be 
Character data if all the keystrokes to be inserted are 
elements of the atomic vector [j4V. A numeric vector allows 
both characters and other keystrokes, such as cursor 
Movements, using the same representation as [)PFKEY and 6 
CARBIN (the numeric result of [INKEY when that keystroke is 
pressed). 


For more information, see "The Type-ahead Buffer" in 
the Programmer's Manual. 


Result 


The system function []INBUF does not return an explicit 
result. 


Effect 


The effect of [INBUF is to add the keystrokes of the 
right argument to the type-ahead buffer. These keystrokes 
are then used when the keyboard opens for input, just as if 
they had actually been typed at the keyboard by the user. 


If no left argument is used, or if the left argument is 


1, the keystrokes are inserted before the current contents 
of the buffer. 
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If the left argument is 0, the right argument replaces 
the previous contents of the buffer, Any previously typed 
or inserted keystrokes are discarded (cleared). 


lf the left argument is 1, the keystrokes are inserted 
after the current contents of the buffer. To avoid possible 
insertion of user-typed keyboard input with DINBUF, use the 
SPOKE that locks the keyboard. 


Examples 


0 -INBUF 


(Clears the type-ahead buffer.) 


TINBUF 385071 'INBUF 'Bill G',CTCNLoDEDIT 'ROLODEX' 


(Looks up "Bill G" in the 
full-screen editor as if the 
locate-string feature had been 
used manually by first storing 385 
(the numeric value for Ctrl L), 
followed by the desired string and 
Enter in the type-ahead buffer, 
then entering the editor.) 


LINBUF 4/TAB 9 (WIN SPECS 


(Repeats an earlier call to (WIN 
and tabs down to the fifth field.) 


ZELX-'O UINBUF '')W$ID PROBLEM'',UTCNL © IDM 


Error Reports 
DOMAIN ERROR 


LENGTH ERROR 


RANK ERROR 


(Changes the workspace name to 
prevent the naive user from saving 
over the original copy with a 
JSAVE command, and clears anything 
typed ahead by user to avoid its 
taking effect under the wrong 
circumstances.) 


The left argument was not 1, 0, or 1. Or, 
the right argument contained negative 
values, values over 32767, or fractional 
values. 


The execution specified requires more space 
than is available in the type-ahead buffer. 
Or, the left argument is a non-singleton 
vector. 


The left argument is not a singleton, or 
the right argument is not a vector or 
singleton. 
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Character of Keyboard Input GINKEY 


ne 


The niladic system function [INKEY returns the value of 
the first character typed at the keyboard or the first 
keystroke in the type-ahead buffer (if any), without waiting 
for any following characters (not even Enter). [INWKEY, as 
described here, is specific to the APL*PLUS/PC System; it 
may be different or absent in other APL*PLUS Systems. 


Syntax 
result - the explicit result 
Result 


The explicit result of LINKEY is a scalar representing 
the first keystroke in the type-ahead buffer (if any). The 
datatype of the result is character by default, but can be 
Changed to numeric by a JPÓKE. If the type-ahead buffer is 
empty, by default, [INKEY waits for a keystroke to report. 
A .PÓKE can change this wait to returning an empty vector as 
the explicit result. 


Effect 


The function -INKEY displays a cursor and waits for 
input. The input is not displayed on the screen when it is 
found, but returned as the explicit result. 


Most keystrokes can be captured by ÜNKEY. Character 
keys return the usual character if the default datatype 
(character) has not been altered. Note that pressing a 
programmed function key places all of the keystrokes stored 
there into the type-ahead buffer, while [INKEY only 
retrieves the first keystroke from the type-ahead buffer 
each time it is used. Any remaining characters there, if 
not othervise captured or cleared, act as subsequent input 
or are executed. The type-ahead buffer can be cleared by: 


O ZINBUF '' 


A BREAK returns a [ITCWUL, and halts execution with a 
weak interrupt. 


Exit returns no value, halts execution vith a strong 
interrupt, and clears the state indicator. 


The Term. key sets a flag to enter terminal mode the 
next time that input would be requested, but gives no value 
to LINKEY (which looks for a subsequent keystroke). 


If the type-ahead buffer is empty, by default, LINKEY 
waits for the user to press a key. The BASIC language 
INKEY$ function does not wait for the user; it returns an 
empty string if no key is pending. A "don't wait" APL 
single character input can be produced either by a [POKE to 
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eliminate the wait from QIWXEY, or by using: 
7140 11 2 0 0 2 QARBIN '* 


This function does not wait for a keystroke if one hasn't 
yet been placed in the type-ahead buffer. 


Examples 

DINKEY A WITH DEFAULT BEHAVIOR, AND PRESS 'à* 
4 

DINKEY a WITE NON-DEFAULT BEHAVIOR (SEE DPOKE) 
65 


‘HIT M FOR MORE, Q FOR QUIT’ o «(C'Q'sDINKEY) / END 
-(CQ'sD-DINKEY)/END a [+ DISPLAYS THE LETTER TYPED. 


a G- WOULD DISPLAY THE LETTER 
^ TYPED FOLLOWED BY A ÜTCNL. 


Error Report 


WS FULL The explicit result requires more 
workspace storage than is available. 
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[INT -- Invoke Interrupt Handler DINT 


The ambivalent system function CINT invokes an 8088 
interrupt routine after optionally setting the CPU general 
registers. (INT, as described here, is specific to the 
APL*PLUS/PC System; it may be different or absent in other 
APL*PLUS Systems. 


Syntax 
result + [INT interrupt 
result + registers [NT interrupt 
result  - the explicit result 
registers - a singleton or vector of 0 to 7 integers 
interrupt - a scalar integer in the range from 0 to 255 
inclusive 
Argumen 


The optional left argument specifies the values of the 
CPU registers to be used upon entry into the interrupt 
routine specified in the right argument. Up to seven 
integers can be given to be used in order as the initial 
values of the AX, BX, CX, DX, BP, SI, and DI registers. Any 
registers with unassigned values will be set to zero. 


The right argument is an integer singleton in the range 
from 0 to 255 inclusive, indicating which interrupt is to be 
invoked. 


CAUTION: The use of DINT with improperly constructed 
arguments may result in a System crash, destroying the 
contents of the active workspace. 


Result 


Upon exit from the interrupt routine, the explicit 
result of [INT is a vector of the seven integer values of 
the corresponding 8088 registers as the left argument, 


Effect 


The effect of DINT n is identical to that of DCALL 
(2054256*n),203. 


The registers are set to the values provided in the 
left argument (if any). The specified interrupt handler is 
then invoked. 


For information on reserving CPU memory for user- 
written interrupt handlers, see your computer manufacturer's 
DOS manual. Note that this technique reduces the workspace 
Size in APL ([WSS$1ZE) by the amount that you reserve until 
the system is re-booted. This reduction in [WSSIZE further 
prevents the loading of workspaces with non-empty state 
indicators which were saved when [WSSIZE was different. 
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Examples 


STARTLINE*+6 © STOPLINE+7 
(Scanlines for standard cursor 
for color display.) 


(256 0,2561STARTLINE ,STOPLINE) “INT 16 e 
(Turn cursor on when it would 
otherwise be off.) 


© 00(11520 0, (MIN*«256*40URS), 256*SECS) "INT 33 
(Set the system clock.) 


O Op(11008 0, YR, DAY + 256xMONTH) DINT 33 
(Set the date.) 


0 0p11777 INT 33 (Set the DOS verify switch.) 
0 0011776 LINT 33 (Reset the DOS verify switch.) 
x/31(13828 0 0 ,N*«1) LINT 33 

31744 (Find the number of bytes of 


free space on disk drive 
number N, where N=0 for disk 


drive A.) 
DINT 134 (End this APL session.) 
a> (DOS prompt.) 
O OpO INT 140 (Clear off-screen scrolling e 


memory, do not save display 
attributes hereafter, starting 
at this point.) 


0 Opt DINT 140 (Clear off-screen scrolling 
memory, do save display 
attributes hereafter, starting 
at this point.) 


1f JINT invokes a DOS I/O function, as LINT 33 does, 
any error that occurs will be intercepted via the DOS 
critical-error-handler vector, and will be reported as a 
DISK ERROR, DRIVE NOT READY, or DISK WRITE PROTECTED error. 


Error Reports 

DOMAIN ERROR The left argument is not integer-valued. 
Or, the right argument is not an integer 
in the range from 0 to 255 inclusive. 


LENGTH ERROR The left argument is a vector of more than 
seven integers, or the right argument is a 


vector but not a singleton. e 
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RANK ERROR Either argument is of rank greater than 
one, but not a singleton. 


WS FULL The explicit result requires more 
workspace storage than is available. 
o If ZINT invokes a DOS I/O function (for example, 
TINT 33), any error that occurs is intercepted and reported 
by Dos. 
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IQ -- Index Origin Dro 


The workspace-related system variable [IIO is the value 
of the index origin used by several APL primitive functions. 


Domain 


The domain for assignment to 070 is a singleton whose 
value is either 0 or 1. 


Value when Referenced 


When J70 is referenced, its value is a numeric scalar 0 
or 1. 


Default Value in a Clear Workspace 


In a clear workspace, the default value for CIO is 1. 


ZI0-Dependent Primitive and System Function 


The value of 070 is used in connection with: 


* computing the result of index generator (monadic 1) 
and index of (dyadic 1) 


* computing the result of roll (monadic ?) and deal 


(dyadic ?) 
* computing the result of grade up (4) and grade dovn 
e» 
* indexing applied to an array (Al. . .)) 


° applying the axis operator to a primitive function 
(OL. . 04) 


* interpreting the left argument to dyadic transpose 
Go. OA) 


* computing the result of GDEF and (FX when an invalid 
argunent is used 


* interpreting the first element of the left argument 
to [WIN and its result. 


Effect 


When generating or referencing index values, the system 
assumes that indices are numbered starting at JIO. 
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Ore+1 Dr0-0 
a5 15 
12345 o1234 
XoS425 X575 
x 
6 7 8 9 10 56789 
Xn) x3] 
8 8 
X[51 X[5] 
10 INDEX ERROR 
xis] 
^ 
x[0] X[0] 
INDEX ERROR 5 
xio] 
1234 (aj 1234 [3] 
3 4 
" ABCDEF ' [2413] "ABCDEF * [2633] 
CDE CDE 
Ve6 23 11 4 76 V«6 23 11 4 76 
aw ay 
54132 43021 
X,[0.5) Y X,[0.51 Y 
6 7 8 910 5 6 
$23 11 476 6 23 
71 
8 
s 76 
373 323 
3.1/2 201 
Error Reports 
DOMAIN ERROR The value being assigned to [IO is a 
singleton whose value is neither 0 nor 1. 
RANK ERROR The value being assigned to [IO is not a 
singleton, 
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DIQSTATE -- Determining the Inpyt/Output State DIOSTATE 


The niladic system function CIOSTÁATE returns 
information on the input source, capture sink, and output 
sinks currently in use. ([JOSTATE, as described here, is 
specific to the APL*PLUS/PC System; it may be different or 
absent in other APL=PLUS Systems, 


Syntax 
result + DIOSTATE 
result - the explicit result 
Result 


The explicit result of []IOSTATE is a character matrix 
of two, three, or four rows. Information on the current 
input source is in row 1, the current capture sink in row 2, 
and the current output sink or sinks in rows 3 and 4. The 
rows, as formatted, are suitable for use as an argument to 
DIN, ICAP, or ZOUT. 


File reservations and passnumbers are not included in 
the result of “IOSTATE. Library numbers and file names 
returned by DIOSTATE may be different from those originally 
specified in the argument to (CAP, LIN, or “OUT. This can 
occur if the file is renamed after being defined as a sink 
or source. 


CAUTION: Additional rows may be added to the result of 
OFOSTATE in the future, and the format of the result may 
change. 


Determining the Input/Output State 


Both the shape and the content of the result of 
DIOSTATE are significant. The significance of the shape is 
às follows: 


* If the result has two rows, no output sink is in 
effect. 


* If the result has three rows, either a terminal 
output sink or a file output sink is in effect. 


* If the result has four rows, a combination output 
Sink is in effect; row 3 contains information on the 
terminal sink and row 4 contains information on the 
file sink. 


1f a terminal or combination output sink is in effect, 
the third row of the result contains a 'D'. 
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1f a file output sink is in effect, the third row of 
the result contains the full file name in the format 
returned by [JFNANES and DFLIB. For a combination output 
sink, the same information is provided, but it appears in 
the fourth row of the result. 


Examples 


The following example shows the result of CIOSTATE in 
the default state (assuming that the I- startup option vas 
not used when APL was started). It is to this state that 
System reverts in response to EXIT (Ctrl Esc). 


l^p[IOSTATE o CIOSTATE 


D (Keyboard input source.) 
(No capture sink.) 
D (Default screen output sink.) 


The next example shows the result of DIOSTATE that is 
returned after a file output sink is specified. 


Z-J0UT '[.OUTFILE' 
DIOSTATE 


1 OUTFILE 


Error Report 


WS FULL The explicit result requires more 
workspace storage than is available. 
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EYW -- v 1 i DKEYW 


The session-related system variable DKEIW contains an 
integer representing the display form in use for executable 
APL expressions, including immediate execution, function 
definition. and latent expressions. For more information. 
see “APL Keyword Form" in the User's Guide. [KEYW, as 
described here, is specific to the APL*PLUS/PC System; it 
may be different or absent in other APL*PLUS Systems. 


Domain 


The domain for assignment to DKEYW is a singleton whose 
value is either 0 or 1. 


Value when Referenced 


When DKEYW is referenced, its value is the numeric 
scalar 0 or 1. 


Default Value at the Start of an Al 


At the beginning of an APL session, the value of UXEYW 
is 0. 


OkEYW-Dependent Primitive and System Functions 


The value of OXEYW is used in connection with the 
representation of those APL primitive symbols not available 
on the text keyboard (the original keytops). 


Ses; 


The value of [KEYW affects the results of TALX, OCR, 
ÜCRL, QCRLPC, DELX, DLX, CSI, DSINL (if system variable 
names are localized), and DYR. It also affects the display 
format of recalled lines of immediate execution input, error 
messages, and function definition. It also affects the 
value that will be stored in IDM by the next error, although 
it does not affect the value currently stored in DDM. 


Effect 


When (KEYW is set to 0, executable APL expressions are 
displayed in APL symbol form beginning vith the next output. 
The APL keyboard layout is selected, starting with the next 
input. 


When [KEYK is set to 1, executable APL expressions are 
displayed in APL keyword form beginning with the next 
output. The text keyboard layout is selected starting with 
the next input. 


For more information about the APL and text keyboards, 
see the User's Guide. 
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Examples 


#keyw 
3 fge #count 5 
111900 
)keyw off (Using ")" on 0 key.) 
) (Recall last line, using ")" on ] key.) 
32i5 
11100 
Error Reports 
DOMAIN ERROR The value being assigned to [KEYW is a 
singleton whose value is neither 0 nor 1, 
RANK ERROR The value being assigned to DKEYW is not a 


singleton. 
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Lin nter Dic 


The niladic system function [LC returns the current 
value of the execution line counter. 


Syntax 
result + DLC 
result - the explicit result 
Result 


The explicit result of DZC is a numeric vector of line 
numbers from the state indicator, beginning with the most 
local. 


The length of the result of DLC in the APL*PLUS/PC 
System may not match the number of rows in the state 
indicator since there is no numeric element corresponding to 
a row containing [ or 2. 


Effect 


While the execution of the system function JLC has no 
effect other than returning its result, it can be used in 
conjunction with + in the expression LC to resume a 
stopped or interrupted execution. 


Example 


usr 
TRI[2]* 
2 
EXAMPLE(3) 
ILe 


WS FULL The explicit result requires more 
workspace storage than is available. 
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DLIB.-- Library List Ore 


The monadic system function [LIB returns a character 
matrix listing all the workspaces and native and component 
files in the designated library, even if the user has no 
access to them. [LIB, as described here, is specific to the 
APL*PLUS/PC System; it may be different or absent in other 
APL*PLUS Systems. 


Syntax 
result + LIB lib 
result - the explicit result 
lib - a singleton integer designating a library, or an 
empty vector 
Argument 
The argument designates the library whose files and 
workspaces are to be listed. 1t must be a positive integer 


or an empty vector (which indicates all active libraries at 
once). 


Result 


The explicit result of [LIB is a 14-column character 
matrix which contains one file identification in each row. 
The columns in the result are defined as follows: 


Column 1 Letter representing a library or disk 
drive 
Column 2 Colon (:) 


Columns 3-14 File name, left-justified, followed by a 
period and the DOS extension 


Libraries 0 through 25 are represented as A through Z. 


The ordering of the rows (file identifications) is 
alphabetic, 


CAUTION: The number of columns in the result of [LIB 
may increase in the future. 


NOTE: )LIB produces the same list of files, not 
alphabetized, but listed in multiple columns to save lines 
on the screen. 

Access 


No special file access code is required for [LIB. 
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pDLIB 10 


[EU 


Error Reports 

DISK ERROR A disk error has occurred, probably due to 
8 hardware fault or to an unformatted or 
defective disk. 

DOMAIN ERROR The argument is not integer-valued. 


LENGTE ERROR The argument is not e singleton or an 
empty vector. 


VS FULL The explicit result requires more 
workspace storage than is available. 
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IBS -- Library to DOS Directory Correspondences UL1855 


The niladic system function [LIBS lists the defined APL 
libraries and the DOS directories into vhich they translate. 
DLIBS is experimental in this release of the APL*PLUS/PC 
System; it may be different, absent, or replaced by an 
entirely different feature in a subsequent release. 


Syntax 
result + LIBS 
result - the explicit result 
Result 


The explicit result of the system function 7178S is a 
74-column-wide character matrix with one line for each 
defined APL library. The line shows the library number and 
the associated DOS directory to which it corresponds. 


The association of a library number and DOS directory 
is made upon entrance into APL, by beginning a session from 
DOS. 


The match of library number to DOS directory is 
determined by the contents of a component of an APL file 
named "APLLIBS", if one was found at session startup in the 
current directory of the default disk drive. Each component 
in the file contains a character vector with a library 
number specification and a full DOS directory specification 
separated by one or more spaces. Since [183 looks for the 
current directory on each disk drive, if A4PLLIBS is in use. 
there must be a disk in each active disk drive. 


In the absence of an APLLIBS file, the default 
association is the disk drive number (0, 1, and so on), and 
therefore the library for the disk in that disk drive (A, B, 
and so on). The current directory of the disk is used as 
the default for that disk drive. The maximum number of 
active libraries (including defaults) is 16. For more 
information on creating an APLLIBS file, see "Sub- 
directories as Libraries" in the File System User's Guide. 


The associations take effect even before interpreting 
any files specified in the startup options (see "Beginning 
and Ending a Session from DOS" in the User's Guide). 


The libraries listed in [LIBS are not guaranteed to 
exist on the indicated disk. Attempts to access or create a 
file or workspace in a library corresponding to a directory 
that has not been created or has been removed from a disk 
results in a LIBRARY NOT FOUND error message. 
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Effect 


If any disk drives have not been used since session 
startup or since the last use of [CMD or )CMD, and if 
non-default libraries have been established at session 
Startup, the system checks the actual current directory in 


the disk drive. 


This has the effect of requiring that a 


disk be present in each disk drive during the system check 
in order to avoid a DRIVE NOT READY halting the process. 


Examples 


MAIL 


Error Reports 
DISK ERROR 


COMPANY \ ACCOUNTS 


(No APLLIBS file was 
found. The current 
directory on the default 
disk drive can be listed 
by [CMD 'CD'. To list 
the current directory on 
another disk drive, use 


LCHD ‘CD d:' where d is 
the DOS disk drive 
letter.) 


(Library 0 is the current 
directory of A.) 


A disk error has occured, probably due to 


a hardware fault or to an unformatted or 
defective disk. 


DRIVE NOT READY 


An attempt has been made to use an empty, 


open, or non-existent disk drive, possibly 
at the direction of the A4PLLIBS file. 


WS FULL 


There is not enough room remaining in the 


workspace for the explicit result of 


ULIBS. 
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ÜL04D -- Load a Workspace Dz0aD 


The monadic system function []LOAD replaces the active 
workspace with a designated workspace. 


Syntax 
DLOAD wsid 


wsid - a character vector or singleton containing a 
workspace identification 


Argument 


The argument to (LOAD is a character vector or 
singleton containing the identification (optional library 
number and name) of the saved workspace to be loaded. 


The workspace can be in any currently active library. 
If no library is specified, the current default library is 
assumed. 


Result 
The function jL04D does not return an explicit result. 


Effect 


The contents of the active workspace are replaced by à 
copy of the contents of the designated library workspace, 
and the SAVED message is displayed at the terminal upon 
Successful completion of the load. The new active workspace 
begins execution automatically if [LX is set appropriately 
in it, thus giving the effect of continuing a multi-step 
program through two or more workspaces. The user can 
communicate data between two workspaces by storing data in a 
file while in one workspace, and then reading the data back 
while in another workspace. 


Examples 


[LOAD 'STAGE2" 
0 STAGE2 SAVED... 
DLOAD 'i PHONENOS' 
1 PHONENOS SAVED . 


Error Repor: 

DISK ERROR A disk error has occurred, probably due 
to a hardware fault or to an 
unformatted or defective disk. 


DOMAIN ERROR The argument has the proper rank but is 
not character-valued. 
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DRIVE NOT READY 


INSUFFICIENT HANDLES 


INVALID WS NAME 


LIBRARY NOT FOUND 


RANK ERROR 


WS NOT COMPATIBLE 


WS NOT FOUND 


WS TOO BIC 
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An attempt has been made to use an 
empty, open, or non-existent disk 
Grive. 


The maximum number of files that DOS 
allows open at one time would be 
exceeded. If you can untie a file, you 
can free a handle for the attempted 
operation, To increase the number of 
handles available, include FILES-n 
(where n is 5 more than the desired 
file tie quota) in your CONFIG.SYS file 
and reboot the system. For the default 
file tie quota of 10, use FILES-1S. 


The specified workspace identification 
is ill-formed. 


The APL library (DOS directory) you are 
trying to use cannot be found on the 
disk in the disk drive indicated by 
ZLIBS. Failure to find the library may 
result from not including a space 
between the library number and 
workspace name. 


The argument is not a vector or 
singleton. 


The specified workspace was saved with 
suspensions under an earlier version of 
the system, from a machine with a 
different amount of memory, or at a 
time when the absolute loading address 
of the APL system was different (for 
example, under a different version of 
DOS). It cannot be loaded under this 
version until )LOAD, )SIC, and )SAVE 
have been executed on the workspace 
under that version of the system. All 
user-defined functions and variables 
can be copied (using )COPY) from the 
local environment, however. 


The designated workspace does not exist 
in the specified or default library. 


The specified workspace is too large to 


load in the amount of memory available 
in this machine. 


Inc. 3-191 System Functions 


LOCK Lock Defined Functions DLOCK 


The monadic system function JLOCK locks the most local 
definitions of a list of functions. 


Syntax 
result + DLOCK fnlist 


result ~ the explicit result 
fnlist - a list of function names 


Argument 


The argument contains a list of zero or more function 
names. It can be represented as any of the following: 


e a character singleton, vector, or matrix containing 
one function name 


e a Character vector containing two or more function 
names with each pair separated by one or more blanks 


e a character matrix with one function name in each 
row, 


Result 


The explicit result of DLOCK is a character matrix of 
any requested function names whose definitions cannot be 
locked. 1f all requested names can be locked, the result is 
an empty matrix with shape 0 0. 


ILOCK locks only the most local definition of a 
function, Functions shadowed by more local use of the same 
name are not locked. 


Effect 


The definitions of all specified functions in the 
active workspace are locked if possible. Locking a function 
also removes any stop or trace settings it may have had (see 
"ÜSTOP -- Stop Function Execution" and "ÜTRACE -- Trace 
Punction Execution"). 


1f [LOCK produces an ERROR or WS FULL, none of the 
functions named in the argument have been locked. 
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Exampl 


oGVR 'TRI' 


72 
pUCR ‘TRI’ 
332 
DLOCK 'TRI' 
eDVR 'TRI' 
0 
pOCR 'TRI* 
90 
DLoCK DNL 3 ^ LOCK ALL FUNCTIONS IN THE WORKSPACE 


Error Reports 

DOMAIN ERROR The argument has the proper rank but is 
not character-valued; or it contains 
invalid identifiers. 


RANK ERROR The argument is not a matrix, vector, or 
singleton. 


WS FULL The explicit result requires more 
workspace storage than is available. 
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t Expression Der 
The workspace-related system variable DIX holds a 
representation of the APL expression to be executed when the 
workspace is loaded. This provides a convenient mechanism 

for conditioning the workspace environment, starting or 
restarting an application, or validating a user's access to 
an application. 


Domain 


The domain for assignment to (ZX is a character 
singleton or vector. 


Value when Referenced 


When JLX is referenced, its value is a character 
vector. 


Default Value in a Clear Workspace 


In a clear workspace, the default value for [LX is the 
empty vector, 


ILX-Dependent Primitive Functions 
No primitive functions depend upon the value of GLY. 
Effect 


Whenever the workspace is loaded, except vhen loaded by 
)XLOAD or [XLO4D, the statement s[LI is executed. If [Lx 
represents an invalid APL statement, an error is reported 
and execution is suspended as if the statement were a line 
entered in immediate execution mode. 


Examples 


The first example shows how [LX can be used to deny 
workspace access to unapproved users. 


ÜEXe'DS4-C-DAZ [1] « APPROVED )/**CLEAR''! 


The following example illustrates a typical latent 
expression for chaining workspaces together. 


V AUTOSTART;TN;F 
n INMEDIATELY BEGIN PROCESSING IN THIS WORKSPACE BY 
a EXECUTING AN APL STATEMENT FROM THE CONTROL FILE 
^ 'O RESTART’ IF THIS FILE IS TIED TO 8243. 
^ 

*('0 RESTART’ v,29+, (CENUMS=TN+8234)4[IFNAMES )0 

2 DFREAD TH,2 


uin 


ÜLX-'AUTOSTART" 
ISAVE SECONDS 
1 SECONDWS SAVED . . . 
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The latent expression will execute the AUTOSTART 
function when SECONDWS is loaded, This workspace is meant 
to be started from a program running in another workspace 
called FIRSTWS. A program running in FIRSTWS can choose 
what APL statement will be executed in SECONDWS when it is 
loaded by executing: 


DQLOAD 'SECONDWS"' 
in FIRSTWS. If a number of arbitrary statements are to be 
executed in SECONDWS by direction from FIRSTWS, they can be 
Stored with the statement: 
'statementiestatement29...ostatementn' .lFREPLACE TN,2 


Or, if there is an arbitrary program to be executed in 
SECONDWS, it can be specified with the statements: 


"eUDEF FREAD TN,3* []FREPLACE TN,2 
(DWR' ARBITRARY') LFREPLACE TN,3 


When SECONDWS is loaded. the specified APL statements vill 
begin the execution in the new active workspace. If the 
file '0 RESTÁART' is not tied when SECONDWS is loaded, the 
AUTOSTART function vill exit without beginning further 
execution. This technique allows a utility workspace in a 
library to be used automatically for different purposes by 
different users. 


Error Reports 


During execution Any APL error report. 


DOMAIN ERROR The value being assigned is not 
character-valued or contains unmatched 
quotes. 

LIMIT ERROR The argument contains the character 


representation of a number whose absolute 
value is greater than 
1.797693134862316£308 or which contains 
more than 19 significant digits. 


LENGTH ERROR The right argument is a vector not of 
length 1. 
RANK ERROR The right argument is a non-singleton of 


rank greater than 1. 
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APPEND 


N: Fi Àj DNAPPEND 


The dyadic system function DNAPPEND appends a value to 
the end of a designated native file. The value is identical 
to the ravel of the value in the left argument. [INAPPEND, 
as described here, is specific to the APL*PLUS/PC System; it 
may be different or absent in other APL*PLUS Systems. 


Syntax 
value [INAPPEND tieno 


x - any APL array 
tieno - a negative integer file tie number 


Arguments 


The left argument is the value to be appended to the 
file. It can be of any rank, shape, or datatype, but will 
be raveled. 


The right argument designates the file (by file tie 
number). The right argument must be a negative, 
integer-valued singleton. 


Result 


The system function JNAPPEND does not return an 
explicit result. 


Effect 


New data is appended to the native file. The datatgpe 
of the left argument automatically determines the conversion 
type used (unlike []NREA4D, where it must be specified). Note 
that the system does not keep a record of the type of data 
stored in native files. The user must therefore remember or 
record the information somevhere so that it can be supplied 
for later data retrieval. In particular, note that an APL 
numeric array, even if it currently contains all integers. 
Can be represented internally as floating-point data. The 
use of floor (L) or ceiling ([) before filing data ensures 
not only integer values, but integer storage format (two 
bytes each) if all values are between 732,768 and 32,767. 


A left argument value of rank greater than 1 is raveled 
to a vector for storage. 


WARNING: (NAPPEND may not immediately place data on the 
disk. t may wait until there is more data or until the 
file is untied using DNUNTIE or )OFF. 
Examples 

(OVR 'TRI') QWAPPEND 727 


LIBRARY ÜNAPPEND ^33 
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Error Reports 


DISK ERROR A disk error has occurred, probably due to 
a hardware fault or to an unformatted or 
defective disk. 


DISK FULL The operation cannot be done in the 
available system storage. Use JFERASE, 
GNERASE, [IFRENAME or )DROP to eliminate 
unneeded storage and try again. 


DISK WRITE The disk now in the disk drive has a 
PROTECTED protective cover over its notch preventing 
any alteration of its contents. 


DOMAIN ERROR The right argument is not a negative 
integer from 1 to 32,768 inclusive. 


DRIVE NOT READY An attempt has been made to use an empty 
or non-existent disk drive. 


FILE TIE ERROR The file tie number is not tied to a file. 


LENGTE ERROR The right argument is a vector not of 
length 1. 
RANK ERROR The right argument is a non-singleton of 


rank greater than 1. 
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INÇ -- Name Classification of Identifiers Orc 


The monadic system function ONC returns the locally 
active classification of a list of identifiers (names). 


result + ANC idlist 


- the explicit result 
- a list of identifiers 


Argunent 


The argument contains a list of zero or more 
identifiers in one of the following forms: 


» a Character singleton or vector containing one 
identifier 


* a vector of identifiers separated by one or more 
blanks 


* à character matrix with one identifier in each row. 
Result 

The explicit result of [NC is a numeric vector of 
classification codes, one for each name in the argument. 
Values that can be returned are 


Value Classification 


o not defined 

1 label 

2 variable 

3 defined function 
4 other 


A value of 4 indicates one of the following: 


* the identifier is a system function, variable, or 
constant (begins vith a quad symbol) 


* the argument is not a valid name. 


When a defined dyadic function is called monadically, 
the left argument has a INC of 0. 


Example 


INC 2 3 p's TRI? 
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Error Reports 


DOMAIN ERROR The argument is not character-valued. 

RANK ERROR The argument is not a matrix, vector, or 
singleton. e 

WS FULL The explicit result requires more 


workspace storage than is available. 


Copyright 1984 STSC, Inc. 3-199 System Functions 


|NCREATE -- Native File Create ONCREATE 


The dyadic system function [WCREATE creates a new 
native DOS file. It establishes a new name and ties the 
file. JNCREATE, as described here, is specific to the 
APL*PLUS/PC System; it may be different or absent in other 
APL*PLUS Systems. 


Syntax 
'fileid.ext' [IWCREATE tieno 
fileid - a character vector containing a DOS file name, 


optionally preceded by a one-letter library 
name and à colon (:) 


ext - DOS file extension 
iieno ^ - a negative integer file tie number 
Arguments 


The left argument must be a character vector or 
singleton designating a valid DOS file identification and 
extension. If the library designator and colon are omitted, 
the current default disk drive is assumed. APL libraries 0 
through 25 are equated to the letters A through Z 
respectively. They are defined at session startup by the 
components of a file named APLLIBS if one is found, and are 
otherwise equivalent to disk drive. 


: DOS does not distinguish between upper- and 
lowercase; although it accepts both upper- and lowercase, it 
stores using uppercase. Do not attempt to use file names 
whose only distinguishing feature is the case of one or more 
letters. 


The extension is a user-chosen mnemonic classification 
consisting of from one to three alphanumeric characters, the 
first of which must be alphabetic. The extensions .ASF and 
.4WS designate APL component shared files and workspaces 
respectively. 

The right argument must be a negative, integer-valued 
Singleton designating an available file tie number. You 
cannot have another file currently tied with this number. 
Result 


The function [WCREATE does not return an explicit 
result. 


Effect 


A new file is created and tied. 


Copyright 1983 STSC, Inc. 3-200 System Functions 


Examples 


'MEMO.TXT' LNCREATE 727 


'PRINT.OUT' [NCREATE ^33 


'BiSCRÁATCH.GIG" 


DIRECTORY FULL 


DISK ERROR 


DISK FULL 


DISK WRITE 
PROTECTED 


DOMAIN ERROR 


DRIVE NOT READY 


FILE ARGUMENT ERROR 


FILE NAME ERROR 


FILE TIE QUOTA 
EXCEEDED 
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ZNCREATE ^25 


There is no space for additional 
names in the directory of this disk 
without first dropping workspaces or 
erasing files. 


A disk error has occurred. probably 
due to a hardware fault or to an 
unformatted or defective disk. 


The operation cannot be done in the 
available system storage. Use 
LFERASE, "NERASE, |FRENAME, or )DROP 
to eliminate unneeded storage. and 
try again. 


The disk now in the disk drive has a 
protective cover over its notch 
preventing any alteration of its 
contents. 


The right argument has the proper 
rank and length, but is not an 
integer from “1 to 732,768 
inclusive. 


An attempt has been made to use an 
empty or non-existent disk drive. 


The left argument which should 
contain the file name or other 
information is ill-formed, numeric, 
or not a vector or singleton. 


The specified file identification is 
already in use for another file on 
that disk drive. 


Performing the operation would have 
caused the user to have more than 
the maximum number of files (twenty) 
tied at once. 


3-201 System Functions 


INSUFFICIENT HANDLES The maximum number of files that DOS 
allows open at one time would be 
exceeded. 1f you can untie a file, 
you can free a handle for the 
attempted operation. To increase 
the number of handles available, 
include FILES-n (where n is 5 more 
than the desired file tie quota) in 
your CONFIG.SYS file and reboot the 
system. For the default file tie 
quota of 10, use FILES=15. 


LIBRARY NOT FOUND The DOS directory (APL library) you 
are trying to use cannot be found on 
the disk in the disk drive indicated 
by LLIBS. 


RANK ERROR The right argument is not a 
singleton. 
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IWERASE -- Native File Erase CNERASE 


The dyadic system function (WERÁASE erases an entire 
native DOS file. The file must be tied.  ^WERASE unties the 
file, and deletes the file name from the disk directory 
(library list). All of the data in the file is destroyed. 
DNERASE, as described here, is specific to the APL*PLUS/PC 


System; it may be different or absent in other APL*PLUS 
Systems. 
Syntax 
'fileid.ext' INERASE tieno 
fileid - a character vector containing a file name, 
optionally preceded by a one-letter disk drive 
identifier and a colon (:) 
ext - DOS file extension 
tieno  - a negative integer file tie number 
Arguments 


The left and right arguments must currently be tied to 
each other. 


The left argument is the file identification of the 
file. If the disk drive identifier is omitted, the current 
default disk drive is assumed. The left argument must be a 
character vector or singleton. 

CAUTION: DOS does not distinguish between upper- and 
lowercase; although it accepts both upper- and lowercase, it 
stores using uppercase. Do not attempt to use.file names 
whose only distinguishing feature is the case of one or more 
letters. 


The right argument designates the file (by file tie 


number). The right argument must be a negative, 
integer-valued singleton. 


Result 


The function IWERASZ does not return an explicit 
result. 


Effect 


A file is untied and erased from the disk. All of the 
data in the file is destroyed. 


Examples 


'B:MEMO.TXT' ^NTIE 727 
'BiMEMO.TXT' “NERASE 727 


"SCRATCB.GIG' CNTIE 33 
'SCRATCB.GIG' “WERASE ^33 
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Error Reports 
DISK ERROR 


DISK VRITE 
PROTECTED 


DOMAIN ERROR 


DRIVE NOT READY 
FILE ARGUMENT 
ERROR 

FILE NAME ERROR 


FILE TIE ERROR 


RANK ERROR 
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A disk error has occurred, probably due 
to a hardware fault or to an unformatted 
or defective disk. 


The disk nov in the disk drive has a 
protective cover over its notch 
preventing any alteration of its 
contents, 


The right argument has the proper rank 
and length, but is not a negative 
integer from 1 to 732,768 inclusive. 


An attempt has been made to use an 
empty, open, or non-existent disk drive. 


The left argument is ill-formed, 
numeric, or not a vector or singleton. 


The left and right arguments do not 
designate the same file. 


The file tie number is not tied to a 
file. 


The right argument is not a singleton, 
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DNL -- 3 


ONL 


The system function {IN} returns a character matrix of 
identifiers (names). The most local definition of an 
identifier is referenced. Functions, variables, and labels 
are selected according to the value of the argument. 


Syntax 


result + CNL integer 
result + letters “NL integer 


result - the explicit result 
tti 


- a character singleton or vector 


s 
r - one or more integers 


The optional left argument to CNL is a character 
singleton or vector which restricts the explicit result to 
names whose first letter is included in the left argument. 


The right argument is an integer-valued singleton or 


vector which determines the class of names produced. The 
acceptable values are 


Value Identifiers 


1 labels 
2 variables 
3 functions 


If more than one class is designated, identifiers defined as 
belonging to any of those classes are returned; for example, 


CWE 2 - produces a matrix of names of all 
variables 

ÜNL 2 3 or CNL 3 2 - produces a matrix of names of all 
variables and functions 


Result 
The explicit result of [INL is a character matrix of 


identifiers. In the APL*PLUS/PC System, the rows of the 
result are alphabetized. 


Example 
ENS 

TRI UPDATE VOID WITH WITHOUT XMIT 
Pce'TY! CNL 3 

TRI 

XHI? 

24 
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Error Reports 
DOMAIN ERROR 


RANK ERROR 
WS FULL 


The left argument has the proper rank but 
is not character-valued, or the right 
argument has the proper rank but is not an 
integer array of valid codes. 


The argument is not a vector or singleton. 


The explicit result requires more 
workspace storage than is available. 
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ONNAMES 
Native Files 


= File Identifications of All Tied DNNAMES 


The niladic system function INWAMES returns the file 
identifications of all files currently tied vith DNTIE. 
LNNAMES, as described here, is specific to the APL«PLUS/PC 
System; it may be different or absent in other APL*PLUS 
Systems. 


Syntax 
result + INNAMES 
result - the explicit result 
Result 


The explicit result returned by INNAMES is a 14-column 
character matrix that contains one file identification per 
row. The rows of the result have the same ordering as the 
result of DNNUMS. 


The 14 columns are defined as follows: 


Column 1: Letter identifying disk drive 

Column 2 A colon (:) 

Columns 3-14 File name, left-justified, followed by a 
period and file extension (.A4SF for APL 
component shared files, .4WS for APL 
workspaces). 


Example 


INNAMES 
BiPERSONS.ASF 
A:PRIMES.INT 


Error Report 

WS FULL Displaying the explicit result would 
require more workspace storage than is 
available. 
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DNNUMS -- File Numbers of All Tied Files ÜNNUMS 


The niladic system function DNAUMS returns the file tie 
numbers of all files currently tied with DWTIE. [NNUMS, as 
described here, is specific to the APL*PLUS/PC System; it 
may be different or absent in other APL*PLUS Systems. 
Syntax 

result + ONNUMS 

result - the explicit result 
Result 


The explicit result of ÜNNUMS is a numeric vector of 
file tie numbers. 


The resuit has the same ordering as the rows of the 
result of (NNAMES. 


Examples 


. ÜNNUMS —— 
27 752 3 37 Ta 


DNUNTIE DNNUMS 


pÜNNUMS 
0 
Error Report 
WS FULL Displaying the explicit result would 
require more workspace storage than is 
available. 
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DNREAD -- Read from Native File CNREAD 


The monadic function [WREAD reads data from a native 
DOS file and returns its value as the result. UNREAD, as 
described here, is specific to the APL*PLUS/PC System; it 
may be different or absent in other APL*PLUS Systems. 


result + “NREAD tieno conv count startbyte 


result - the explicit result 

tieno - a negative integer file tie number 

conv - an integer designating the conversion to be 
Used on the datà that is read 

count - a positive integer designating how many 


elements of type cony are to be read 

Startbyte - a positive integer representing the starting 
byte (0 to ^1*«2331) at which reading is to 
begin, in origin 0. 


Argument 


The argument designates the file (by file tie number), 
the conversion type. the element count of the result, and 
optionally the byte at which reading is to begin. If the 
starting location is omitted, it is assumed to be where the 
last native file operation on this file finished, or at the 
beginning of the file if there has been no LNREAD, 
ÜNREPLACE, or [NAPPEND since the file was last tied. 
Retying an already tied file with (NTIE (slippery tie) will 
reset the starting location to the beginning of the file: 
this also occurs when a file is retied after returning from 
)CMD or “CMD. The argument must be an integer vector of 
three or four elements, of which only the first element is 
negative. 


The conversion types are 
82 - read one byte per element, result character 
163 - read two bytes per element, result integer 


645 - read eight bytes per element, result 
floating-point data. 


The explicit result of []NREAD is the value of the data 
in the file as an APL vector. 


Effect 
A copy of the specified data on file is brought into 


the workspace. converted into the specified form of APL 
data. 
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Example 


ÜNREAD 12 82 57 0 
THIS FILE CONTAINS SALES DATA FOR 1981. CREATED 1/26/83. 


or r. 


DISK ERROR 


DOMAIN ERROR 


DRIVE NOT READY 


FILE INDEX ERROR 


FILE TIE ERROR 


LENGTH ERROR 


RANK ERROR 
WS FULL 


A disk error has occurred, probably due to 
a hardware fault or to an unformatted or 
defective disk. 


The argument has the proper rank and 
length, but contains a negative value in 
other than the first element, is not 
integer-valued, has a tie number of zero 
or less than ~32,768, the conversion type 
is not 82, 163, or 645, or the starting 
byte indicator exceeds ~1+2*31. 


An attempt has been made to use an empty, 
open, or non-existent disk drive. 


One or more of the specified locations to 
be read lie outside the limits of the 
file. 

The file tie number is not tied to a file. 


The argument is not a vector of exactly 
three or four elements. 


The argument is not a vector. 


The explicit result requires more 
workspace storage than is available. 


Copyright 1983 STSC, Inc. 3-210 System Functions 


|INREPLACE -- Ri Native File Data ÜNREPLACE 


The dyadic system function []WREPLACE stores a new value 
in an existing native file storage space, replacing the data 
already there. (ONREPLACE, as described here, is specific to 
the APL*PLUS/PC System; it may be different or absent in 
other APL*PLUS Systems. 


Syntax 
valve [WREPLACE tieno startbyte 


ne - any APL array 
- a negative integer file tie number 
FT E - a positive integer representing the starting 
byte (0 to ^1*2*31) where the new data is to 
be placed 


The left argument is the value to be stored in the 
file. It can be of any rank, shape, or datatype. It will 
be raveled by CWREPLACE, 


The right argument designates the file (by file tie 
number). It must be an integer-valued, two-element vector 
with a negative first element and a positive second element. 
Result 


The function []WREPLACE does not return an explicit 
result. 


Ef, 


t 


The value of the designated storage space on the file 
is changed. If the storage from the specified startbyte to 
the end of the file is insufficient for the specified value, 
the file is extended to accommodate it. 


WARNING: LWREPLACE may not immediately place data on the 
disk. It may wait until there is more data or until the 
file is untied using [INUNTIE or )OFF. 


Example 


BLOCK+QNREAD ~33 163 10 1048520 
BLOCK 

23 7 1984 722 79 22 48 41 68 82 
BLOCK(3]-1982 " 
BLOCK [NREPLACE ^33 1048520 


Copyright 1983 STSC, Inc. 3-211 System Functions 


Error Reports 
DISK ERROR 


DISK FULL 


DISK WRITE 
PROTECTED 


DOMAIN ERROR 


DRIVE NOT READY 


FILE INDEX ERROR 


FILE TIE ERROR 
LENGTE ERROR 


RANK ERROR 


A disk error has occurred, probably due to 
a hardware fault or to an unformatted or 
defective disk. 


The replacement value is larger than the 
space from the starting location to the 
current end of the file, and the operation 
cannot be done in the storage available on 
the disk. Use ÜFERASE, UNERASE, or )DROP 
to eliminate unneeded storage and try 
again, 


The disk now in the disk drive has a 
protective cover over its notch preventing 
any alteration of its contents. 


The right argument has the proper rank and 
length, but contains a negative second 
element, is not integer-valued, has a tie 
number not in the range ^i to 32,768 
inclusive, or has a starting byte 
indicator greater than ^ 1*2*31. 


An attempt has been made to use an empty, 
open, or non-existent disk drive, 


The specified starting location lies 
outside the limits of the file. 


The file tie number is not tied to a file. 


The right argument has the proper rank, 
but does not have exactly two elements. 


The right argument is not a vector or 
singleton. 
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Native DNRESIZE 


The dyadic system function DNRESIZE alters the size of 
a native file on the disk. It is, therefore, useful for 
pre-allocating space to reduce fragmentation, or for 
discarding material at the end of the file. CWRESIZE, as 
described here, is specific to the APL*PLUS/PC System; it 
may be different or absent in other APL*PLUS Systems. 


Syntax 
newsize DWRESIZE tieno 
newsize - the number of bytes of disk storage to be 
allocated to this file 
tieno - a negative integer file tie number 


Arguments 


The left argument to [WRESIZE is the new file size in 
bytes. It should be a non-negative, integer-valued 
Singleton in the range 0 to 2,147,483,647 ( 1*2*31). 


The right argument designates the file tie number to be 
used. The right argument must be a negative, integer-valued 
singleton currently in use as a tie number. 


Result 


The system function (NRESIZE does not return an 
explicit result. 


Effect 


The effect of GNRESIZE is to change the amount of disk 
space allocated for the file. If the new size is smaller 
than current size, any material beyond the new end point in 
the file is lost. Any subsequent use of [NAPPEND adds 
material at the new end of the file. 


Examples 

32768 DNRESIZE 7312 (Reserves 32 kilobytes on the 
disk for use in the file tied 
to 7312.) 

0 CNRESIZE 717 (Discards all data in the file 
tied to 17, but preserves its 
directory entry.) 

Err rts 
DISK ERROR A disk error has occurred. probably due 


to a hardware fault or to an unformatted 
or defective disk. 
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DISK FULL 


DISK WRITE 
PROTECTED 


DOMAIN ERROR 


DRIVE NOT READY 


FILE TIE ERROR 


LENGTH ERROR 


RANK ERROR 


The specified size would require more 
Space than currently available on the 
disk. 


The disk now in the disk drive has a 
protective cover over its notch 
preventing any alteration of its 
contents. 


The left argument has the proper rank and 
length, but is not a non-negative integer 
or exceeds 2,147,483,647. The right 
argument has the proper rank and length, 
but is not a negative integer from “1 to 
32.768 inclusive, 


An attempt has been made to use an empty, 
Open, or non-existent disk drive. 


The file tie number is not tied to a 
file. 


The right argument is a vector not of 
length 1. Or, the left argument is not a 
singleton. 


The right argument is a non-singleton of 
rank greater than 1. 
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DNSIZE Pile Size Information DNSIZE 


The monadic system function [INSIZE returns a scalar 
showing the amount of disk storage occupied by a file. 
DNSIZE. as described here, is specific to the APL*PLUS/PC 
Syste it may be different or absent in other APL*PLUS 
Systems. 


Syntax 
result + (NSIZE tieno 


resylt - the explicit result 
fieno - a negative integer file tie number 


Argument 


The argument designates the file (by file tie number). 
The argument must be a negative, integer-valued singleton. 


Result 


The explicit result of [NSIZE is a numeric scalar 
indicerina the total disk storage (in bytes) used by the 
le. 


[NSIZE can also be used with component files or 
workspaces if they have been tied with []NTIE. 


binis e 


'AIPRIMES.ASE! JNTIE 737 


INSIZE 73? 

233472 

Error Reports 

DOMAIN ERROR The argument has the proper rank and 
length, but is not an integer in the 
range 1 to 32,768 inclusive. 

LENGTH ERROR The right argument is a vector not of 
length 1. 

RANK ERROR The right argument is a non-singleton of 
rank greater than 1. 

WS FULL The explicit result requires more 


workspace storage than is available. 
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IJNTIE -- Tie Native File ONTIE 


The dyadic system function [INTIE establishes a file tie 
for a native DOS file. WTIE, as described here, is 
specific to the APL*PLUS/PC System; it may be different or 
absent in other APL*PLUS Systems. 


Syntax 
'fileid.ext' DWTIE tieno 
fileid - a character vector containing a DOS file name, 
optionally preceded by a one-letter library 
identifier and a colon (:) 
ext - DOS file extension 
tieno ~ a negative integer file tie number 
Arguments 


The left argument must be a character vector or 
Singleton designating the DOS file identification and 
extension of an existing file. If the library designator 
and colon are omitted, the current default disk drive is 
assumed. APL libraries 0 through 25 are equated to the 
letters A through Z respectively. They are defined at 
session startup by the components of a file named APLLIBS if 
one is found, and are otherwise equivalent to disk drive. 


CAUTION: DOS does not distinguish between upper- and 
lowercase; although it accepts both upper- and lovercase, it 
stores using uppercase. Do not attempt to use file names 
whose only distinguishing feature is the case of one or more 
letters. 


The right argument designates the file tie number to be 
used. The right argument must be a negative, integer-valued 
singleton not currently in use as a tie number. 


Result 

The function Owrre does not return an explicit result. 
Effect 

The native file is tied, 


A file that is already tied with JNTIE can be re-tied 
using [NTIE without first being untied. The tie number can 
be the same number or a different number. The only 
restrictions are that no other file can already be tied with 
the new tie number and the file cannot be tied to a positive 
number (extension .ASF only). This "slippery" tie can be 
used to verify that a file is tied (without looking up its 
name in QNNAMES). 
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Examples 


à 


' AsPRIMES .INT* 
'BiPRINT.OUT' 
Error Reports 
DISK ERROR 


DOMAIN ERROR 


DRIVE NOT READY 


FILE ARGUMENT ERROR 


FILE NOT FOUND 


FILE TIE ERROR 


FILE TIE QUOTA 
EXCEEDED 


INSUFFICIENT HANDLES 


LIBRARY NOT FOUND 


LENGTH ERROR 


RANK ERROR 
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INTIE 737 


CNTIE 7i 


A disk error has occurred, probably 
due to a hardware fault or to an 
unformatted or defective disk. 


The right argument has the proper 
rank and length, but is not an 
integer from “1 to 732,768. 


An attempt has been made to use an 
empty or non-existent disk drive. 


The left argument is ill-formed, 
numeric, or not a vector or 
singleton. 


The file named is not in the 
specified or default disk drive. 


The file tie number is already tied 
to another file. Or, the specified 
file is still tied from an earlier 
use of J]FTIE or FSTIE. 


Performing the operation vould have 
caused the user to have more than 
the maximum number of files (twenty) 
tied at once. 


The maximum number of files that DOS 
allows open at one time would be 
exceeded. If you can untie a file, 
you can free a handle for the 
attempted operation. To increase 
the number of handles available, 
include FILES=n (where n is 5 more 
than the desired file tie quota) in 
your CONFIG.SYS file and reboot the 
system. For the default file tie 
quota of 10, use FILES-15. 


The DOS directory (APL library) you 
are trying to use cannot be found on 
the disk in the disk drive indicated 
by "LIBS. 


The right argument is a vector not 
of length 1. 


The right argument is a non- 
singleton of rank greater than 1. 
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[NEUNTIE -- Native File Untie DNUNTIE 


The monadic system function LNUNTIE unties designated 
files that were tied using DWTIE. NUNTIE, as described 
here, is specific to the APL*PLUS/PC System; it may be 
different or absent in other APL*PLUS Systems. 


ÜWUNTIE tieno! tieno2 tieno3 . . 


tieno - a negative integer file tie number 


Argument 


The argument designates the file tie numbers of the 
component and/or native files tied with "WTIE to be untied. 
The arqument can be a singleton or a vector of zero or more 
file tíe numbers. Elements of the argument do not have to 
be distinct nor must they designate tied files. An empty 
vector is permitted as an argument, and does not affect any 
file ties. The argument must be a numeric vector or 
singleton. 


Result 


The function “NUNTIE does not return an explicit 
result. 


Eifect 


The files tied to any of the tie numbers in the 
argument are untied, and their DOS directories on disk are 
updated. 

WARNING: To avoid damaging your files always make sure that 
the disk that was in the disk drive when you tied 
a file is in that disk drive when you untie that 
file. 

Untying native files ensures that all data written to 
the files and the updated file directories are placed on the 


disk before it is removed from the disk drive, or before the 
data is lost by a power failure or a system reset. 


Examples 
ÜNUNTIE ^33 


LNUNTIE [WNUMS 
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Error Reports 


DISK ERROR A disk error has occurred, probably due to 
a hardware fault or to an unformatted or 


defective disk. 
DISK FULL The operation cannot be done in the o 
storage available in the specified 
library. Use JFERASE, [NERASE, JFRENAME, 
or )DROP to eliminate unneeded storage, 
and try again. 


DISK WRITE The disk now in the disk drive has a 
PROTECTED protective cover over its notch preventing 
any alteration of its contents. 


DOMAIN ERROR The argument has the proper rank, but 
contains one or more values other than 
integers in the range from ^1 to 32,768 
inclusive. 


DRIVE NOT READY An attempt has been made to use an empty. 
open, or non-existent disk drive, possibly 
at the direction of an 4PLLIBS file. 


RANK ERROR The argument is not a vector or singleton. 
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QUT ini e Outpyt Sink Dour 


E 


The monadic system function (OUT specifies the output 
sink (where to display or store output) for the remainder of 
the session, and indicates the success of the output sink 
specification or a reason for failure. DOUT, as described 
here, is specific to the APL*PLUS/PC System; it may be 
different or absent in other APL*PLUS Systems. 


Syntax 
result - Jour 'sink' 


result - the explicit result 
Sink  - a description of the output sink to use. 


Argument 


The argument to ovr is a character singleton or vector 
that specifies the output sink to use. Superfluous blanks 
are ignored. Possible forms of the argument and the output 
sinks they define are 


" No output sink, 

d Screen output sink. 
'filesink' File output sink. 
"J,filesink" Combination output sink. 
"filesink,]" Combination output sink. 


A file output sink filesink consists of a file 
specification: a file name, optionally preceded by a 
library number, and optionally followed by a reservation, a 
password, or both. Specifically, filespec can be 


'fileid reservation :passnumber' 
where the reservation is used to resize an existing file or 


to set the reservation for a file that is to be created, and 
:passnumber is a file passnumber if the file already exists. 


Result 


The explicit result of Jour is an integer scalar that 
indicates the success of the output specification or its 
reason for failure. If the result is anything other than 1, 
the output state has not been changed by COUT. 


Result Meaning 


1 Specified capture sink established successfully. 
2 Unable to interpret specification. 
3 111-formed passnumber, 
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10 FILE NAME ERROR (name is ill-formed, or 
passnumber is specified for a non-existent 


file). 

11 FILE TIED (with SNTIE). 

12 FILE ACCESS ERROR, one of the following 
meanings: 


* File exists but the user account number in 
use does not have append access. 


* File exists and reservation specified, but 
user account number in use does not have 
resize access. 


* File exists but wrong passnumber is 
specified; if the file is already tied, the 
passnumber associated with the current tie 
must be used. 


13 FILE DAMAGED. 

17 FILE SIZE ERROR, file reservation specified is 
Smaller than the amount of space already used by 
the file. 

25 FILE TIE QUOTA EXCEEDED. 

Fii DRIVE NOT READY. 

28 DISK ERROR. 

29 DISK FULL. 

30 DIRECTORY FULL. 

31 DISK WRITE PROTECTED. 

32 LIBRARY NOT FOUND. 

33 INSUFFICIENT HANDLES. 

Effect 


The effect of Jour is to establish the output sink or 
sinks to be used from the point of execution on; that is, to 
direct output to a file, to the screen, or both. 


Note that the use of BREAK to generate a weak interrupt 
(a single short stroke) will suppress the output in progress 
only to the screen, not to a file output sink. A strong 
interrupt, two BREAK strokes in rapid succession or holding 
down the keys, may halt a running program, but vill not 
prevent any output already generated from going to a file 
output sink. 
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Note that if screen output is not being used and 
execution halts as a result of encountering an error, CDM 
will not display on the screen. Since error handling with 
DELX can be used to trap and resolve the error, the default 
behavior is to revert to screen output on error only after 
executing DELY. You can override the default behavior and 
force screen display of [DM by including instructions to 
that effect in your [ELX. For example: 


DELX«DALY- '0 0 pDOUT ''C'' e [pm 


Without this precaution, you may not know that an error has 
occurred. 


ixamples 

Gour '* (No output sink; all 
output is discarded.) 

Cour 'D' (Screen output sink, the 
normal output state.) 

DOVT 'OUTFILE' (File output sink.) 

DOVT 'OUTFILE,?' (Combination output sink 
recording complete 
session.) 

COUT 'OUTFILE 100000' (File output sink, 


resized or created at 
100,000 bytes.) 


DOUT 'OUTFILE:32725' (File output sink, 
existing locked file.) 


Gour 'i RESULTS 500000:9050' (File output sink; 
existing passnumbered 
file resized to 500,000 


bytes.) 
Err rts 
DOMAIN ERROR The argument is of proper rank, but is 
not character valued. 
RANK ERROR The argument is character, but is not a 
singleton or vector. 
WS FULL The explicit result requires more 


workspace storage than is available. 


The folloving errors may occur while using a file 
Output sink, and result in the diagnostic message being 
recorded in []DM, but not in the output sink file; DELY is 
not executed; any capture sinks and output sinks in use are 
switched off; input reverts to the keyboard and output 
reverts to screen only. 
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DOUT DISK ERROR A disk error has occurred during 
the attempt to append to the 
Output sink file, probably due to 
a hardware fault or to an 
unformatted or defective disk. 


DOVT DISK FULL Recording the most recent output 
would require more space than is 
currently available on the disk. 


Dour DISK WRITE PROTECTED The disk now in the disk drive 
where the output sink file is 
expected has a protective cover 
over the notch preventing any 
alteration of its contents. 


TOUT DRIVE NOT READY The disk drive that should 
contain the output sink file is 
not ready for use, possibly empty 
or with its latch door open. 


DOUT FILE DAMAGED The output sink file has invalid 
valves in its component 
directory, possibly from having 
replaced the disk while the file 
was tied. 


DouT FILE FULL Recording the most recent output 
would exceed the file reservation 
of the output sink file. 


Jour FILE TIE ERROR The output sink file has been 
erased from DOS using ICMD. 


Side effects from other errors or interrupts: input reverts 
to the keyboard, and screen output is added to any output or 
capture sinks in effect, if a file input source is exhausted 
or if the system encounters a strong interrupt, an untrapped 
error (including system command errors), a trapped error 
where (JELX¥ cannot be executed, a trapped error where DELX 
does not restart execution by a branch or by executing 
JERROR, or a weak interrupt where QALX cannot be executed or 
where the execution of DALX does not restart the interrupted 
execution. 
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IPCOPY --Pj ir M kspace OPcory 


The system function [IPCOPY can copy all or some APL 
functions or variables (but not labels) from the local 
environment of a saved workspace into the local environment 
of the active workspace. It does not copy any objects from 
the saved vorkspace whose names are currently defined in the 
active workspace. 


ntax 
result + DFCOPY wsid 
result + obilist [PCOPY wsid 
result - the explicit result 
wsid - a character vector or singleton containing the 
workspace identification 
obilist - character vector, singleton, or matrix 
containing a list of functions and variables to 
be copied 
Argument 


The optional left argument to DPCOPY is a list of 
objects to copy into the active workspace. It can be a 
Character singleton, a character vector, with one or more 
Spaces between object nai or a character matrix with one 
name per row. If the list is empty, nothing is copied. 


If no left argument is given, all objects are copied. 


The right argument to DPCOPY is a character vector or 
singleton containing the identification (optional library 
number and name) of the saved workspace from which to copy. 


Result 


The explicit result of DPCOPY is an integer vector 
representing the success or failure of the copying 
operation. 


1f dyadic JPCOPY is used, the explicit result includes 
one integer for each name in the list, indicating success or 


failure in copying thet object. The folloving codes are 
used: 


2 - a variable by that name vas successfully copied 

1 - a function by that name vas successfully copied 

0 - no object by the specified name was found 

1 - names already defined in the active workspace 
cannot be copied 

2 - object vas too large for available space in the 
active workspace 

a - not enough space in symbol table (no objects have 
been copied) 

6 - no space to compare symbol tables, or to store long 
names that are in the list or used in functions in 
the list. 
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If monadic JPCOPY is used, an empty result indicates 
that all the objects in the saved workspace vere 
successfully copied. If one or more objects were not copied 
because their names were already defined in the active 
workspace, the result is a numeric vector using the same 
error codes. 


If an unanticipated error occurs, no explicit result is 
returned (see "Error Reports", below). 


Effect 


If the specified objects are found in the local 
environment of a saved workspace, the name of the saved 
workspace matches the specified wsid, and the saved 
workspace has an empty state indicator, the objects are 
copied into the local environment of the active workspace. 
The explicit result indicates whether they are functions or 
variables, and whether any objects were not found or not 
copied. 


DPCOPY will not replace an object by the same name 
already in the active workspace. Therefore, its effect is 
similar to that of )PCOPY. 


Copying a function removes any STOP and JTRACE 
settings for it in the saved workspace. 


The time required to complete a copy operation is 
dependent more on the size of the workspace named in the 
copy command than on the size of the items in objlist. Copy 
times of over one minute are common when the workspace 
stored on disk grows as large as 100,000 bytes. See "Hints" 
in the Programmer's Manual for suggestions about saving time 
by avoiding copying objects into the active workspace. 


Example 


)VARS 
MATRIX 
MATRIX 
12 
34 
ISI 
SUSPENDED[3]* 
M "MATRIX XXX DATA SUSPENDED' GPCOPY 'WS3' 
10271 
VARS 
DATA MATRIX 
MATRIX 


12 
a4 
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Error Reports 


DISK ERROR 


© DOMAIN ERROR 


DRIVE NOT READY 


INSUFFICIENT HANDLES 


INVALID WS NAME 


& LIBRARY NOT FOUND 


RANK ERROR 


WS FULL 


WS NOT FOUND 


A disk error has occurred, probably 
due to a hardware fault or to an 
unformatted or defective disk. 


One argument is not character-valued, 
or the left argument contains an 
ill-formed APL identifier (object 
name). 


An attempt has been made to use an 
empty or non-existent disk drive. 


The maximum number of files that DOS 
allows open at one time would be 
exceeded. If you can untie a file, 
you can free a handle for the 
attempted operation. To increase the 
number of handles available, include 
FILES=n (where n is 5 more than the 
desired file tie quota) in your 
CONFIG. SYS file and reboot the 
system, For the default file tie 
quota of 10, use FILES=15. 


The right argument contains an 
ill-formed workspace identification. 


The APL library (DOS directory) you 
are trying to use cannot be found on 
the disk in the disk drive indicated 
by ÜLIBS. Failure to find the 
library may result from not including 
a space between the library number 
and workspace name. 


A non-singleton left argument has a 
rank greater than 2, or a 
non-singleton right argument has a 
rank greater than 1. 


There is not enough space in tne 
workspace for the explicit result. 


No workspace by that name is 
currently in the specified or default 
library. 
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IPEEK -- Peek into CPU Memory SPEER 


The scalar monadic system function [PEEK reads the 
values currently stored at specified CPU memory locations in 
your personal computer.  JPEEK, as described here, is 
Specific to the APL*PLUS/PC System; it may be different or 
absent in other APL*PLUS Systems. 


Syntax 
result + “PEEK locations 


result - the explicit result 
locations - an integer array specifying which memory 
positions to read 


Argunent 


The argument to “PEEK is an array of integers in the 
range from 32,768 to 65,535 inclusive. Values from 32768 
through 65535 are used as equivalent to the values 32767 
through ^1 respectively, and both are used as 65536|n. 

These integers represent CPU memory locations. They are not 
absolute addresses, but relative to the value of SEG. 


You can use “PEEK at all of the locations listed for 
UPOKE. 


Result 
The explicit result of [PEEK is an integer array of the 


value(s) stored in the specified location(s}. The shape of 
the result matches the shape of the argument. 


Examples 

DSEG-.0 (The system's default.) 

OPEEK 101 (Indicates whether the machine is 
using an 8087 chip to do its 
floating-point arithmetic: 0 means 
"no^; 255 means "yes".) 

(PEEK 99 (Are Break and Exit currently 
disabled? 0 means "no" and 1 means 
"yes" .) 

ÜPEEK 125 126 (What port and translation are used 
for the current system printer?) 

Error Report 
DOMAIN ERROR The argument is not an integer in the 


range “32,768 to 65,535. 
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IPFKEY -~ Set or Report Contents of Programmed OPFKEY 
Function Key 


The ambivalent system function []PFKEY installs or 
reports sequences of keystrokes on the programmed function 
keys. OPFXEY, as described here, is specific to the 
APL«PLUS/PC System; it may be different or absent in other 
APL*PLUS Systems. 


Syntax 


result + ÜPFKEY key 
value [PFKEY key 


result - the explicit result 

value - the sequence to be installed on the specified 
programmed function key 

key ^ - an integer from 1 through 30 inclusive, or "i 
through 30 with monadic use, specifying the 
programmed function key 


Arguments 


The left argument to [PFKEY is a vector representing 
the value to be installed on the specified programmed 
function key. The value can be specified as a character 
vector, or aS an integer vector. In an integer vector, the 
characters in [MY are represented as their zero-origin 
indices in [47, and other keys (like cursors) are 
represented by values higher than 255 (typically 256 added 
to the zero-origin index in DAY of the character returned by 
QINKEY for that key). Integer values for special keys can 
also be produced directly by [INKEY when its result is 
numeric after the appropriate GPOKE. 


Not all integer values over 255 have meaning. Those 
having no meaning are stored but ignored. Other special key 
values include: 


440 through 449 for the function keys F1 through F10 

450 through 459 for the function keys used with Shift 

460 through 489 for the function keys used with Alt 

470 through 479 for the function keys used with Ctrl 

321 through 323 for Shift Print, Ctrl Print, and Keyb 
respectively 

326 for the Term. key 

41? for Ctrl S 


Certain immediate action keys cannot be stored in 


programmed function keys: Exit, Slover (the Alt or Red key 
used alone), BREAK, Hold, and More. 
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The right argument to DPFKEY represents the programmed 
function key whose value is to be changed or reported. A 
negative key number causes a numeric explicit result. The 
unshifted Fi through F10 programmed function keys are 
represented by the integers 1 through 10 respectively. When 
used with Shift (the Green key), the values are increased by o 
10. When used with Ctrl, they are increased by 20. 


Result 


The monadic use of the system function JPFKEY returns 
the current value of the specified programmed function key 
as an explicit result. If the right argument is a positive 
number, the result is character data. If the right argument 
is the negative of the programmed function key's number, the 
result is numeric. 


The dyadic use of GPFKEY does not return an explicit 
result. 


Effect 


The effect of monadic LPFKEY is to return a vector 
representing the current value of the specified programmed 
function key as a sequence of keystrokes that would be typed 
in if the key were pressed. The result is a charecter 
vector for a positive right argument, and an integer vector 
for a negative right argument. 


The effect of dyadic JPFKEY is to replace the current [ 
value associated vith the specified programmed function key 
with the value given as the left argument. Thus, subsequent 
pressing of the key is equivalent to typing the specified 
sequence. 


Note that once a complete set of programmed function 
keys has been installed by using JjPFKET, it can be captured 
in its entirety by using: 


TISEG+8 o jSEG-2561-PEEK 130 129 
PPKEYS+ OPEEK -.10-11054 


A complete set that has been captured using the above 
statement can be reinstalled with a single corresponding 
DPOKE. This is useful for simulating the localization of 
the programmed function keys, or for installing an 
application's set more quickly. 


You can also install permanent programmed function key 
values on disk in the APL«PLUS/PC System by tying the 
APL.EXE file (here shown in library 0) as follows: 


'APL.EXE' -NTIE 3 © PFLOC-16* NREAD 73 163 1 8 
DAV LPFKEYS«I0] .NREPLACE "3. PFLOC e 
DNUNTIE ^3 


Be sure to reset [SEG to a more usual value before trying to 
use DPEEK, ÜPOKE, or any APL function that might use them. 
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mples 


")LOAD ' 


DPFKEY 2 
)L04D 


CIT 44DYR 


DPFKEY 2 (Sets programmed 
function key F2 to 
type ")L04D ^.) 


(Displays the 
Current value of key 
92.) 


teres Orcas) DPEKEY 1 (Sets programmed 
function key F1 to 
type 1+[¥R '* and 
backspace so that 
vhat is typed next 
is inserted between 
the quotes.) 


394 236 388 32 91 149 93 391 391 391 391 [PFKEY 9 


(Sets programmed 
function key 9 to 
open ¥ function 
definition mode in 
either of two ways: 
press F9 when the 
cursor is on an 
empty line, type a 
function name, and 
press Enter; or move 
the cursor to any 
column on a line 
that already shows 
(only) a function 
name, press F9, and 
press Enter.) 


(Press programmed function key 9, and it types:) 


v0) 
Error Reports 
DOMAIN ERROR 


LENGTH ERROR 


The right argument contains character data 
or contains a numeric value whose absolute 
value is not an integer in the range from 
1 to 30 inclusive; or, the left argument 
contains numeric valves which are 
negative, non-integral, or greater than 
32767, Or, dyadic [PFKEY has been used 
from a programmed function key where it is 
followed by a non-final DTCNL. 


The left argument exceeds 255 elements, or 
the programmed function key definition 
would cause the total number of characters 
stored in programmed function keys to 
exceed 512. Or, the right argument is not 
a singleton. 
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RANK ERROR The left argument is not a vector or 
singleton. 


WS FULL There is insufficient space in the 
workspace for the explicit result. 


Copyright 1983 STSC, Inc. 3-231 System Functions 


to CPU Memory POKE 


Poke 


The scalar dyadic system function POKE replaces the 
values currently stored at specified CPU memory locations in 
your personal computer, 7PÓKE, as described here, is 
Specific to the APL*PLUS/PC System; it may be different or 
absent in other APL«PLUS Systems. 


+ values “POKE locations 

- the explicit result 

- an array of integers to be placed in memory 
- an integer array specifying which memory 

positions to change 


Argument 


The left argument to GPOKE is an array of integer 
values from 0 through 255 inclusive to replace those 
Currently in the memory locations specified in the right 
argument. 


The right argument to .POKE is an array of integers in 
the range from 732,768 to $5,535 inclusive. These integers 
represent CPU memory locations. They are not absolute 
addresses, but are relative to the value of C376; see the 
list of useful locations at the end of this section. Values 
from 32766 through 65535 are used as equivalent to the 
values 32767 through 1 respectively, and both are used as 
65536|n. Negative address values represent addresses higher 
than 32767 (hexadecimal ?FFF). 


Result 


The explicit result of LPOKE is an integer array of the 
value(s) just replaced. The shape of the result matches 
that of the arguments. 


CAUTION: Using []POKE with improper locations or values 
can cause system crashes and other system failures. 


Examples 
0 GPOKE 98 (Turn off the chirp sent by remote CPU.) 
E (The chirp vas on -- the system 


default.) 


OLDSYSPRI«2 2 LPOKE 125 126 
(Switch system printer to second serial 
port (COM2) with untranslated ASCII, 
saving old values.) 
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Error Reports 


DOMAIN ERROR The left argument is not an integer in the 
range 0 to 255, or the right argument is 
not an integer in the range 732,758 to 
65,535. 


LENGTH ERROR Neither argument is a singleton, and their 
shapes do not match. 


Locations 

This section documents the memory locations to use with 
DPEEK and )POKE to discover or modify indicator values that 
control system behavior. For additional system behavior 
controls, see "DOS and the APL*PLUS/PC System" in the 


Programmer's Manual, and the other system variables and 
functions in this manual. 


NOTE: Random use of [POKE could cause significant damage. 


The two-byte integers of the APL*PLUS/PC System 
(732,768 through 32,767? or 0 through 65,535) are not 
adequate to represent all the memory locations (absolute 
addresses) in your computer. Thus, an offset is used for 
ÜPEEK and JPOKE values (see "LSEG -- Memory Segment for 
Peeking and Poking"). 


CAUTION: If the value in DSEG is not the proper one, 
OPEEK and [POKE will use the wrong memory locations. In the 
case of [JPOKE, this may cause an immediate crash or subtle 
damage that may never be discovered but could invalidate 
various results thereafter. The default value of SEG, an 
empty vector (8), is assumed for all the addresses shown 
in this section unless explicitly noted otherwise. This 
value is automatically adjusted for the location the APL 
system was loaded. This location is different in various 
sized machines with various amounts of reserved memory. 


Since the feature descriptions are listed 
alphabetically by the underscored key vords, a map from 
memory locations into the appropriate key word or phrase 
precedes the list of feature descriptions. Note, too, that 
the HELP file provided with the system also documents most 
of these locations and can be activated either by location 
number (for example, )#ELP 100) or by topic (for example, 
)RELP POKE LINEFEEDS). 


If you have only the ÜPOKE location, find its 
associated underscored word in the table that preceeds the 
alphabetical reference. 


To discover (rather than change) values, substitute 


(PEEK (with no left argument) for POKE in the examples 
below. 
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IPOKE_ location 


171-175 
176-17? 
178 
184 
186 
187 
188 
189-190 
197-198 
199 
208 
222-226 
230 
234 
235 
237-238 
241-242 
246-249 
254 
255 
256 
258 
260 
261 
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Reference word 


filehelper 

addition 

prompt 

default drive 

chi 

Break (disable) 
linefeed 

8087 (before A) 
duplex 

printer 

terminal (mode) 
keyboard 

overstriking 

wrap 

garbage collect 

port 

translation 

drives 

programmed function keys 
keyword marker 
scrolling 

insertion 

cursor size 

numeric pad 

attribute 

width 

clear line 

Break (limit strength) 
Break (simulate) 
CapsLock 

Help 

highlight 

terminal (key changes) 
graphics font 

line numbering 

TARBIN 

Monitor (color code) 
column number 

key clicks 

graphics ađapter 
keyboard table 
Monitor (key) 

Alt and Ctrl keys 
local-only 
single-line mode 
ÜGPRINT orientation 
keyword output negative 
startup option 
assembler input 
overstrike table 
DINKEY's wait 
ÜINKEY's datatype 
editor changes 

editor exit 

editor session pending 
insertion or replacement 
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282 cursor display 


263 attribute values 

264 editor window 

269 keywords enabled/disabled 
270-273 margins in editor 

274 keyboard locked/unlocked 

275 keyboard for session 
276-278 session startup values 
279-282 CGPRINT header and trailer 

283 terminal mode keyboard 

284 graphics mode 

289 file tie quota 

activate/suppress use of 8087 (255 or 0) [POKE 101 


Turns on or turns off the system's indication of 
whether an 8087 chip (or equivalent floating-point 
co-processor) is installed. The default value is set 
according to whether there is such a chip in the 
machine. If your machine has one, the system will turn 
on the indicator. 1f your machine does not have one or 
if you turn off the indicator, the system will behave 
as if the chip is not installed. If you turn on the 
indicator without such a chip in the machine, the 
system will hang; you must bootstrap the system again, 
losing everything in the active vorkspace. 


Set file growth addition size n []POKE 95 
Sets the value of n. When an APL file has no set file 
reservation and more space is needed, n times 512 bytes 
of disk space are added. The default value at session 
Start is 8; therefore, for a file with a reservation of 
zero, 4096 bytes of disk space are added. 


disable/enable extra Alt and Ctrl (78 or 0) LPOKE 208 
Disables or enables the "extra" Alt(-) and Ctrl(*) keys 
next to the numeric keypad. The default value is 78 
(enabled). 

disable/enable partial display (0 or 1) DCPOKE 184 


of 0 11 CÁARBIN 


Disables or enables the keystroke-by-keystroke display 
of keyboard input to [ARBIN inport 11 without waiting 
for complete explicit result. The termination 
character does not display. The default value is 0. 


assembler input call OFFSET~256 4 DPEEK 242 241 
SEGMENT-256 4 “PEEK 130 129 


The segment and offset needed for an assembler far call 
to the APL*PLUS/PC System's keyboard input routine 
(comparable to .INKEY with no wait for key not yet 
pressed) for use in writing CALL routines. 
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simulate BREAK or Exit (o, 


select default attribute n OPOKE 161 


The display attribute value n is used for positions on 
new and inserted lines as they are created. See the 
list of attributes under "[WGET -- Get Window Data". 
The default value is 7 (white characters on black 
background, normal intensity, non-blinking). 


select generic attribute values (0 or 1) GPOKE 263 


Selects the IBM-specific or generic interpretation of 
attribute values for use with WGET, [WIN, and OWPUT. 
The default value is 0 (IBM-specific attribute values). 
The generic attribute values are 


normal (white on black) 
inverse video 

high intensity 
blinking 

underscored 


seneo 


Any combination of the non-zero attributes can be 
represented by using the sum of the values for those 
attributes when generic attributes are in effect. 


disable/enable BREAK and Exit (1 or 0) IPOKE 99 


Disables and enables both BREAK and Exit for use in 
interrupting processing, output, or input. If BREAK 
and Exit are disabled, only the power switch or system 
reset (Ctrl Alt Del) can be used to interrupt 
processing or output, thereby destroying the contents 
Of the active workspace. The default value at session 
start is 0. 


limit strength of BREAK and Exit (0, 1, 3, or 7) SPOKE 164 


If BREAK and Exit have not been disabled by 0 (POKE 99, 
this sets an upper boundary on how strong a BREAK may 
be entered. The values 0, 1, 3, and 7 represent 
respectively no interrupt, weak interrupt, strong 
interrupt, and total exit. If a stronger BREAK is 
entered, it is demoted to the strongest currently 
allowed. The default value is 7. 


3, or 7) SPOKE 165 


Simulates under program control the keyboard entry of 
no interrupt (0), weak interrupt (1), strong interrupt 
(3), or Exit (7). Default value is 0. Automatically 
resets to 0 when the interrupt has been handled (by 
DALX or other means). Can be used to see if a weak 
interrupt is pending ([PEEK 165). 
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set or unset CapsLock (1 or 0) OPOKE 166 


Turns on (1) or off (0, the default) the CapsLock for 
use with the text keyboard (it is ignored with the APL 
keyboard). When CapsLock is on, the 26 letter keys 
produce capital letters when used without the Shift 
key. 


Sound or silence chirp (1 or 0) []POKE 98 


Sounds or silences the audible chirp sent by remote 
devices in terminal mode (corresponding to the ASCII 
BEL used to signal the next line of input and certain 
entry errors). The default value is 1 (on). 


disable/enable clear line before output (0 or 1) SPOKE 163 


Blocks or restores the default behavior of erasing 
everything on a line of the screen before performing 
normal output on it. This feature is always 
automatically disabled in function definition mode and 
terminal mode. 


disable/enable column number display (0 or 1) QPOKE 187 
Disables or enables the automatic display and constant 
updating of the column number of the cursor position in 
the full-screen editor on the bottom line. The default 
value is 0 (disabled). 


disable/enable cursor display (0 or 1) POKE 262 
Disables or enables cursor display during 0 11 [ARBIN. 
The default value of 0 displays no cursor; a value of 1 
displays a cursor. 


Change cursor size size JPOKE 1 0 + type 


Specifies the cursor size and position (hov tall, and 
whether high or low) for any of five cursor states. 
Keeping in mind that characters generated by an IBM 
monochrome monitor are 14 scan lines high and those 
generated by an IBM color monitor are only 8 scan lines 
high, you can choose the height of tne cursor by 
specifying a two-element vector gize. The first 
element of the vector is the scan line on which the 
cursor begins, and the second element is the scan line 
on which it ends. Acceptable values for type are 


default 
type in the above formula begin end 
150 regular cursor for color 6 7 
152 = regular cursor monochrome m 12 
154 = color terminal and (IINKEY 5 ? 
156 = monochrome terminal and CINKEY 9 12 
158 overstrike (Ins key) b Lir 
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A cursor with a start line below its stop line vraps 
up and is hollow in the middle. The top line is 0. A 
cursor that starts and stops on scan line 32 

(SIZE = 32 32) is invisible. 


@ set default drive (n + 48) DPOKE 97 


Together with [INT, as described below, changes the 
default disk drive that is used when a disk drive 
specification is not given (in “CREATE, )SAVE, and so 
on). The default value at session start depends on the 
current default disk drive in DOS. For disk drive A, 

n = 0; for disk drive B, n = 1; and so on. You must 
also use 0 0 p (3584 0 0, n) DINT 33 to complete the 
change. 


number of logical drives in use OPEEK 128 


Tells how many logical disk drives are in the machine 
configuration. 


set full- or half-duplex n DPOKE 115 
Any non-zero value of n establishes full-duplex 
operation for use in terminal mode. The default value 
at session start is 0. 

changes made in full-screen editor DPEEK 256 

e A value of 0 means that keystrokes able to change an 

object were used during the last edit session. A value 
of 161 means that Ctrl S was used during the last edit. 

exit taken from full-screen editor OPEEK 258 


Shows the most recent method used to exit the 
full-screen editor. The interpretation of the values 


is 
0 - BREAK or Exit, or editor unused in this 
session 
20 - CtrlE 


142 - Ctrl X 
159 - Ctrl Q 


Thus, the values 0 20 from [PEEK 256 258 indicate that 
the definition of the object in the workspace has been 
changed. 


or left margin 256 1 JPEEK 271 270 


The character position of the left margin used by Ctrl 

W (also set by Ctrl Y) in the full-screen editor. This 

value is session-related rather than workspace-related. 
e It can be reset by (256 256TNEVVALUE) POKE 271 270. 
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256 1 ‘PEEK 273 272 


The character position of the right margin used by Ctrl 
W (also set be Ctrl Z) in the full-screen editor. This 
value is session-related rather than workspace-related. 
It can be reset by (256 256TNEWVALUE) -POKE 273 272. 


full-screen editor session pending DPEEK 260 


A non-zero value indicates that an edit session is 
pending. The system status line also shows this. 


or window height (0 or 1) DPOKE 264 


When the value is 1 (the default), the full-screen 
editor only uses those lines on the screen that pass 
through the current window, but uses their ful] width. 
If the window height is set to 1, the editor will 
override this LPOKE and use the entire screen. When 
the value is 0, the editor uses the entire screen. 


filehelper (1 or 0) POKE 94 


Keeps or discards the use of the access matrix for the 
next “FSTIE or _FTIE operation, When the access matrix 
is overridden, the effect is the same as having an 
empty access matrix -- only the file owner has access, 
but he has full access Therefore, only the file owner 
benefits from overriding the access matrix; he can 
perform operations not previously allowed. The default 
value at session start is 1, and each use of [JFSTIE or 
JFTIE resets it to 1. 


file tie quota LPEEK 289 


The file tie quota of the current APL session. If not 
altered by the F: startup option, the default file tie 
quota is 10. 


forced garbage collect n LPOKE 121 


A value of i forces a garbage collection in the 
workspace every time the keyboard unlocks for input. A 
value of 0 (the default value) causes garbage 
collection only vhen additional space is needed. 


IGPRINT orientation (0 or 1) CPOKE 234 


Makes JGPRINT print graphic images without rotating 
them by 90 degrees. Default (0) allows the maximum 
area of the screen to be printed by rotating the image 
90 degrees. 
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d trailer strings 256 4 [jPEEK 280 279 
256 1 [PEEK 282 281 


These values tell the starting locations of the 
character strings sent before and after (respectively) 
the use of [GPRINT to prepare and restore the printer 
for and after printing of graphics. These strings 
terminate with the first 0 (NUL) found. The default 
Strings support the EPSON GRAFTRAX style of printing 
graphics. Replacing these strings allows support of 
other printers (for example, the IBM Color Printer). 


start of graphics adapter table 256 2 [PEEK 190 189 


Determines the starting location of the parameter 
blocks for the graphics display adapters. 


start of graphics f 256 1 PEEK 177 176 


Determines the starting location of a table that 
defines the bit patterns used by “¢WRITE. Each element 
of Cav is stored as eight successive bytes, one per 
scan line. The bit pattern can be viewed as 0(8p2)T 
the eight bytes. Allows user-defined character sets. 
This character set is also used as the dot-matrix 
printer font for translation 3. 


forced exit from graphics mode (0 or 1) DPOKE 284 


e A value of 1 forces the system to return to text mode 
whenever it enters immediate execution mode (comparable 
to the use of Exit). The default value of 0 requires 
an explicit return (either Exit or 3 [INT 16) to 
character mode, suitable for use with a two-monitor 
system, 


set HELP screen width n SPOKE 169 


Uses the specified screen width (n) for HELP facility 
and Map displays, allowing developers with 80-column 
screens to see how much of their HELP screen will 
display on a color monitor in 40-column mode. The 
value of n can safely range from 0 to the actual screen 
width. The default is 0, representing the current real 
physical screen width, 


select highlight attribute D OPOKE 170 
The display attribute value n is used to define 
highlighted positions in the HELP facility and in the 


full-screen editor. The default value at session start 
is 112. 
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DINKEY's datatype (0 or 1) [POKE 255 


The explicit result of DINKEY is a character if the 
value here is 0, but numeric if the value is 1. The 
default value is 0. 


LINKEY's wait for key not yet pressed (0 or 1) CPOKE 254 


With a value of 1 here, DINKEY waits for a keystroke if 
the type-ahead buffer is empty. With a value of 0, 
DINKEY returns an empty result if the buffer is empty. 
The default value is 1. 


select insertion or replacement (1 or 0) LPOKE 149 


The default value is 1, which inserts characters at the 
cursor position, and anything on the line to the right 
of the cursor moves over to make room for the inserted 
characters. The value 0 causes typed characters to 
replace (overwrite) the characters at the cursor. 


select insertion or replacement (0 or 1) ZPOKE 261 
for output 


The default value of 0 causes output (implicit or 
requested) to replace characters to the right of the 
cursor. A value of 1 causes output to insert, pushing 
characters past the cursor to the right. This LPOKE 
will make output very slow, so it should be used for 
special tricks only, and restored afterward. 


disable/enable key clicks (0 or 1) [JPOKE 188 


Disables or enables speaker simulation of key clicks 
when a key is pressed or autorepeats. Default value is 


0 (off). 
CAUTION: Higher values may cause instability in the 
system. 

keyboard for session OPEEX 275 


The value of 1 indicated that the session was begun 
with the unified keyboard (K-U). A value of 0 
indicates that the APL or text keyboard was selected: 
DKEYV indicates which is in use. 


keyboard locked/unlocked (1 or 0) JPOKE 274 
When the value here is 1, no type-ahead is accepted: 
the system beeps if keys are pressed, The default 


value of 0 is restored by any request for input from 
either the system or any executing APL expression. 
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select keyboard state n DPOKE 118 


This value represents the keyword setting of the system 
(like DKEYW) and, except in sessions using the unified 
keyboad, can switch from the APL keyboard (value=0) to 
the text keyboard (valuez:1), or, by poking in a value 
greater than 1, change to the text keyboard and disable 
the Keyb key. The default is 0 if the text keyboard 
has not been selected with startup option K=. With the 
unified keyboard, this poke affects only the output 
form. 


start of keyboard table TAB+256 1 ZPEEK 198 197 


TAB is the starting location of the internal table that 
defines the keyboard interpretation; that is, the JAV 
values of the keystrokes returned by each of the keys 
on the keyboard, The keyboard definition can be 
modified by poking different values into this table. 
The table has eight bytes per key: 


Position For APL & Text ____For Unified 
Col unshifted text unshifted 
[1] shifted text shifted 
[21 Alt text (unless Alt 
defined as keyword 
assist) 
[31 unshifted APL undefined 
[a] shifted APL undefined 
[51 Alt APL undefined 
tel keyword assist value, Shift Alt 
0 if on numeric pad; © if on numeric pad; 
255 if none 255 if not on numeric 
pad, but undefined 
(7) Ctrl Ctrl 


The 83 eight-byte table entries are arranged in the 
order of the manufacturer's key-button numbers (see 
your computer manufacturer's technical manual). The 
value returned by a given key in a given keyboard mode 
(0 - 7 from the above table) is TAB*MODE*8xKEY-1. For 
example, the key to the right of the "P" key gives 'í' 
on the shifted APL keyboard because (with KEY:26 and 
NODB=4) 123 is the result of 65 [POKE T4B*4*8x26-1. 
Aná: 


[I0«-0 o STORE + 255 []POKE TAB*6*8x170 


places APL characters on the Alt text keyboard (an 
early approximation of the unified keyboard). And: 


Y-26 166 244 16? 151 245 235 
V []POKE TAB+204 212 329 340 211 323 339 


sets the APL keyboard to values used in IBM's PC APL. 
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CAUTION: Do not attempt to change a key that is 
defined as a "special" key on the current keyboard to a 
"regular" (character) key (or vice versa). 


select keyword marker n LPOKE 147 


Selects the character, if any, used as a visible prefix o 
on keywords. A value of 0 means no visible marker; 

this causes all 207 keywords to become reserved words 

-- words that look like user variables and functions, 

but that you cannot use because they are reserved for 

the system definition. Other characters are specified 

as the zero-origin index into IAV. The default is 35, 
representing #. 


keyword output negative symbol n -POKE 235 


Specifies the character used in keyword mode for the 
APL high-minus (7) sign in default output, and output 
from both monadic and dyadic v. The value n 
represents the character /AV[ I0«n]. For example, 45 
[POKE 235 would use the mid-minus (-) instead of the 
default value 35 ("). 


WARNING: This character is used for output only. 
Handling negative numbers during input is the 
programmer's responsibility. 


keywords enabled/disabled (0 or 1) UPOKE 269 © 


The default value of 0 enables keyword output. A value 
of 1 disables keyword output when displaying functions 
(even when {KEYW is 1) except for the choice of 
negative symbol ( ), controlled separately by I 
235. In addition, this disables keyword assist. 


IKE 


select line numbering in full-screen (1 or 0) POKE 179 
editor 


Select whether numbered lines will or will not be in 
use on entry into the full-screen editor. While in the 
editor, this can be changed by Ctrl O, with the new 
value preserved. The default value is 1 representing 
line numbering in use. 


set/suppress automatic linefeed (0 or 1) JPOKE 100 


Turns on or turns off the automatic linefeed option for 

the parallel printer ports and port 10 (user-defined). 

When the option is on, each ASCII CR transmitted is 

paired with an ASCII LF. This is useful if the printer 

or other remote device needs a linefeed character to 

roll the paper up a line for each new line of output. 

The default value at session start is 0 (linefeeds o 
supplied). 
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set 


loc. (0 to 255) DPOKE 222 


Set up to five terminal mode transmission keys as 
local-only by poking their  INKEY value into one of the 
locations 222, 223, 224, 225, or 226. 


e enable/disable Monitor key (1 or 0) (IPOKE 199 


Enables or disables the Monitor key's switching 
Character entry between color and monochrome monitors 
when both are installed. The default value is 0 
(disabled). 


CAUTION: Do not enable the Monitor key unless you have 
both monitors installed. 


select color mode for Monitor (0, 1, 2, or 3) DPOKE 186 


Select which color mode the Monitor key svitches to 
when enabled. The values are those used for the last 
element of DCRT. The default is 3 if session startup 
is in monochrome, or the value in use if session 
startup vas on a color monitor. 


Select numeric pad or cursor pad (16 or 0) DPOKE 160 


The default value at session start is 0, representing a 
cursor pad. The value 15 converts it to a numeric pad. 
To determine if a numeric pad is selected, use 
1434(8/2)TOPEEK 160. Note that regardless of which pad 
you are using, you can use the Shift key to give the 
appearance of having switched from one pad to the 
other. 


keyboard overstrike table 256 1 [PEEK 247 246 


256 1 [PEEK 249 248 


25610PEEK 257 246 gives the address of the beginning of 
the table of 117 pairs of characters that the system 
accepts as overstrikes. 2564 PEEK 249 248 gives the 
address of the beginning of the matching list of 117 
resulting overstruck characters. Only the first 109 
are used by the system, with zeros in the remaining 
positions. This allows up to eight additional pairs to 
be inserted for new overstrikes. Both the pairs and 
the resulting character list must be bounded by zeros. 
The zeros in what would otherwise be a 118th set must 
be left in place. 


select overstriking with ^TCBS n OPOKE 119 


The default value at session start is 0, which 
disallows overstriking with Orcas during output. 
Non-zero values allow backspace overstriking, but 
output slows as a side-effect. 
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select system print port n TPOKE 125 


turn 


Selects the port to be activated by the Print key and 
by 1 [IPOKE 116. The possible values (which match those 
for GARBIN) are 1, 2, 3, 4, 5, and 10. The default 
value at session start is 3 (LPT1) unless another value 
was used at session startup with P-. 


CAUTION: When a value other than 3 is used, no warning 
beep sounds when you try to use a printer that is not 
ready. 


system printer on or off (1 or 0) DPOKE 116 


Turns on or turns off the system printer. The default 
value at session start is 0 (off). If you turn on the 
indicator without a printer being connected to the 
machine, the system will hang for approximately 15 
seconds. 


start of printer font 256 1 (PEEK 177 176 


The start of the dot-matrix printer font used for 
translation 3. This character set is the same as the 


graphics font. 


keep/discard T- prompt output in next (0 or 1) LPOKE 96 
* input 


JsEG 


Keeps or discards the character prompt displayed at the 
beginning of the next character input request (when 
there are no intervening newline ([]TCNL) characters). 
Keeping the prompt is useful for word processing or for 
editing applications or self-documenting storage of 
answers; discarding it is useful for isolating answers 
to questions for further processing. The default value 
at session startup is 0. 


for programmed function keys 256 1 LPEEK 130 129 


Gives the DSEG value that with zero-origin allows 
peeking or poking 11054 to read or set the values of 
the programmed function keys. The shape of the vector 
on each key is found in ()PEEK 130 and the values 
follow. 


protect/release scrolling memory (1 or 0) JPOKE 148 


Protects (1) material that has scrolled off the screen 
into scroll-back memory by discarding further material 
that would otherwise (0) displace it. The default 
value is 0, allowing retention of material vhich 
scrolls off the screen (within the limits of the 
Selected memory size). Note that when scrolling memory 
is protected, the erasuring keystrokes that otherwise 
erase beyond the bottom of the screen are limited to 
erasing what is on the screen. 
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user-defined session startup values (PEEK 276 277 278 


These three locations are initialized during session 
startup to the numeric values used in the DOS command 
that loaded APL after the user-definable session 
startup optional parameters X=, and Z= 
respectively. The values 0 through 255 inclusive can 
be used. For unspecified Y=, Y=, and Z=, 0 is used. 
The APL session itself does not use the values in these 
locations, but users can pass information from outside 
the APL session to a program that expects to find it 
here. 


change characters on monitor screen n [POKE 2x (12000)--IO 


Puts characters into individual screen locations. 
(NOTE: You must specify [SEG - 20480 for most 
monochrome monitors, or 18432 for most color and 
graphics monitors, in order to assign an address of 0 
to the upper-left corner of the IBM monitor's screen.) 


These values can be produced for other equipment using 
the formula: 


ZSEG-161('0123856789A4BCDEF ' AHEXADDRO -D10 


where the #EYADDR is the starting segment address for 
the screen in hexadecimal as furnished by the 
manufacturer; if the address is in absolute (5 hex 
digits) form, drop the final 0 to obtain the ZEXADDR 
segment address. With the value of [SEG appropriately 
set, the even-numbered positions, starting with 0, are 
character locations. The next higher position controls 
the display attributes. The characters placed on the 
screen this way are DAV[n + JI0J. Similar effects can 
be achieved using (WINDOW and DWPUT. 


WARNING: Do not leave the value of DSEG at this 
setting when you have finished your screen activities. 


enable/disable single line mode (1 or 0) JPOKE 230 


Allows alternate line-entry mode to be enabled, in 
which horizontal cursor movement vill not go beyond the 
left or right end of a physical line. In addition, any 
insertions that would move characters into the 
rightmost column will not be allowed (the system will 
chirp and ignore the insertion). This mode is designed 
only to facilitate data entry. Displaying already 
wrapped lines may cause inconsistent behavior. The 
default value is 0 (disabled). 
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E- startup option used this session 256 1 CPEEK 238 237 


Gives the value of the E- option used at session 
Startup. (See "Session Parameter Values" in the 


User's Guide for an explanation of the values in this 
location.) This cannot be safely changed during a 
session. 


Change terminal key values B ZPOKE 171 through 175 


The character(s) transnitted by certain keys when in 
terminal mode can be altered. Values of n are 
expressed as origin 0 indices in DAV. Note that NULS 
(0) are not transmitted from these keys, and that if a 
NUL is poked into 172, no local clear-to-end-of-line is 
performed. The default values are 


Where Key Default ASCII 
171 172 Untype= 8 10 (BS LF) 
173 Delete- 127 (DEL) 
174 175 Alt Home=12, 00 (NUL NUL) 
Switch into terminal mode 1 OPOKE 117 


Svitches into terminal mode the next time the keyboard 
unlocks for input. You can return to the workspace in 
your personal computer with the Term. key or the Exit 


key (Ctrl Esc). e 


terminal mode keyboard switching (0 or 1) DPOKE 283 


Enables or disables the switching of terminal mode and 
keyboard state between APL and text vhen sending or 
receiving Ctrl N and Ctrl O in terminal mode. The 
default value of 0 enables the switching response. 


set the translation for the system printer n ÜPOKE 128 


Selects the translation type to be used when the system 
printer is activated by the the Print key used with 
either the Shift key or the Ctrl key or by 1 =POKE 116. 
The possible values for n match those used with RBIN. 
At session startup, the default value is 2 
(untranslated ASCII) unless another value was used at 
session startup with T=. 
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set the format width for CELIB, (0 or 1) GPOKE 162 
OWSLTB, and so on 


A value of 0 narrows the format of DFLIB, DFNAMES, 
TWS1D, and “WSLIB to the ten-column format used by 
Release i (Versions 2.0 and 2.6) of the APL*PLUS/PC 
System. A value of 1 (the default) provides the 
twenty-two column format that matches the mainframe 
versions of the system. 


set the wrap marker D CPOKE 120 


Selects the screen attribute used to mark visibly on 
the screen the continuations of wrapped lines. The 
possible values for n match the attributes listed for 
UwGET. The value appearing here, being used in the 
leftmost column of the screen, does not in itself 
constitute wrapping a line, but wrapped lines are 
displayed that way. The default value at session start 
is 1 (underline attribute). 
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-BP -- Printing Precision Ope 


The workspace-related system variable DPP specifies the 
maximum number of significant digits, or print precision, 
provided by the system when it displays numeric 
floating-point data using either default output or monadic 
format (v). 


Domain 


The domain for assignment to DPP is a singleton whose 
value is an integer between 1 and 17 inclusive. 


Value when Referenced 


When DPP is referenced, its value is a numeric scalar 
that is an integer between 1 and 17 inclusive. 


Default Valve in a Clear Workspace 


In a clear workspace, the default value for IPP is 10. 


The value of CPP is used when computing the result of 
monadic format (v) on floating-point arguments. Also, all 
system-formatted output of floating-point data is governed 
by GPP. 


Effect 


For both system-formatted output and the result of 
monadic formatting, the system uses up to “PP significant 
digits in the representation of floating-point values. If a 
value cannot be represented exactly with .PP digits, the 
result is rounded to _PP digits. 


NOTE: =PP+17 permits display of full internal 
precision, with every internal floating-point value 
distinguishable from its nearest neighbors. The final digit 
may not be otherwise significant. 


Examples 


IPP 
10 
+3 
0.3333333333 
2+3 
0.666656565667 
+8 
0.125 (Requires fewer than 10 significant digits.) 
#32 
0.03125 
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ÜPP-3 


+32 
0.0313 (Only 3 significant digits are displayed.) 
Opp+2 
+32 
0.031 
Error Reports 
DOMAIN ERROR The value being assigned to CPP is a 
Singleton whose value is not an integer 
between 1 and 1? inclusive. 
LENGTE ERROR The value being assigned to ZPP is not a 


Singleton. 
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Jev -- Printing Width Dev 
The séssion-related system variable JPW controls the 


maximum number of character positions or print columns 
available to the system for displaying output. 


Domain 


The domain for assignment to “PW is a singleton whose 
value is an integer between 30 and 255 inclusive. 


Value when Referenced 


When “PW is referenced, its value is a numeric scalar 
that is an integer between 30 and 255 inclusive. 


Default Value et the Start of an APL Session 
At the start of an APL session, the value of JPW is 80. 
EV Dependent Primitive and System Functions 


The value of 7PW is used during output from monadic 
format (¥), FMT, default output from executing a statement 
creating an explicit result not otherwise stored, and 
requested output (I+ or T+). 


Effect 


The system uses no more than the first LPW print 
positions on each line during output. Output that would 
extend beyond this number of positions is "folded" onto 
subsequent lines that are indented six spaces. The display 
of numeric data is folded between numbers. 


Examples 


CPW (Display the value of DPW at session 
80 startup.) 


DOMAIN ERROR The value being assigned to DPW is a 
singleton vhose value is not an integer 
between 30 and 255 inclusive. 


LENGTE ERROR The value being assigned to DPW is not a 
singleton. 


Copyright 1984 STSC, Inc. 3-245 System Functions 


LiQLOAD -- Quietly Load a Workspace Dero4D 
The monadic system function DQL04D replaces the active 
workspace with a designated workspace, without displaying 
the SAVED message. 
Syntax 
DQLOAD wsid 


wsid - a character vector or singleton containing the 
workspace identification 


Argument 


The argument to (]@£04D is a character vector or 
singleton containing the identification (optional library 
number and name) of the saveó workspace to be loaded. 


The workspace can be in any active library currently 
defined. If no library is specified, the current default 
library is assumed. 


Upon successful completion of the load, the contents of 
the active workspace are replaced by a copy of the contents 
of the designated workspace. No SAVED message is displayed. 


When DQLO4D is used, the new active workspace begins 
execution automatically if [zx is set appropriately in it, 
thus giving the effect of continuing a multistep program 
through two or more vorkspaces. The user can communicate 
data between two workspaces by storing data in a file while 
in one workspace, and then reading the data back while in 
another workspace. 


Example 


)CLEAR 

CLEAR WS ae 

DQLOAD 'STAGE2' a NOTE, NO SAVED MESSAGE 
WSID a [WSID SHOWS NEW WORKSPACE ID 

1 STAGEZ 
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Error Reports 


DISK ERROR 


DOMAIN ERROR 


DRIVE NOT READY 


INSUFFICIENT HANDLES 


INVALID WS NAME 


LIBRARY NOT FOUND 


RANK ERROR 


WS NOT COMPATIBLE 


WS NOT FOUND 


ws TOD BIG 
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A disk error has occurred, probably due 
to a hardware fault or to an 
unformatted or defective disk. 


The argument has the proper rank but is 
not character-valued. 


An attempt has been made to use an 
empty or non-existent disk drive. 


The maximum number of files that DOS 
allows open at one time would be 
exceeded. 1f you can untie a file, you 
can free a handle for the attempted 
operation. To increase the number of 
handles available, include FILES-n 
(where n is 5 more than the desired 
file tie quota) in your CONFIG.SYS file 
and reboot the system. For the default 
file tie quota of 10, use FILES:15. 


The specified workspace identification 
is ill-formed. 


The APL library (DOS directory) you are 
trying to use cannot be found on the 
disk in the disk drive indicated by 
CLIBS. Failure to find the library may 
result from not including a space 
between the library number and the 
workspace name. 


The argument is not a vector or 
Singleton. 


The specified workspace was saved with 
suspensions under an earlier version of 
the system, from a machine with a 
different amount of memory, or at a 
time when the absolute loading address 
of the APL system was different (for 
example, under a different version of 
DOS). It cannot be loaded under this 
version until )L04D, )SIC, and )SAVE 
have been executed on the workspace 
under that version of the system. All 
user-defined functions and variables 
can be copied (using )COPY) from the 
local environment, however. 


The designated workspace does not exist 
in the specified or default library. 


The specified workspace is too large to 


load in the amount of memory available 
in this machine. 
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ORL 
The workspace-related system variable []RZ is the seed 
value (or random link) used by the pseudo-random number 
generator. [RZ can be assigned a specified value in order 
to reproduce test results (by resetting [JRL to the same 
value each time) or to "randomize" results (by setting ORL 
to an arbitrary value such as the time of day or connect 
time). 
Domain 


The domain for assignment to DRL is any integer from 1 
to 2,147,483,646 ( 2«2*31), inclusive, 


Value when Referenced 

When DRL is referenced, its value is a numeric scalar 
that is an integer from 1 to 2,147,483,606 ( 2*2*31) 
inclusive. 
Default Value in lear Workspace 

1n a clear workspace, the default value is 16807 (7*5). 
D&L-Dependent Primitive Functions 


The value of [RL is used in computing the result of the 
roll (monadic ?) and deal (dyadic ?) primitive functions, 


Effect i 


As each pseudo-random number is generated, the seed 
(ORL) is used in the computation and is also changed. 


Examples 


)CLEAR 
CLEAR WS. . 


16807 


984943658 


DRL«15807 


964943658 
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Error Reports 


DOMAIN ERROR The value being assigned to IRL is not an 
integer in the range 1 to 2,147,483,646 
inclusive. 

LENGTH ERROR The value being assigned to [JRL is a @ 


vector but is not a singleton, 
RANK ERROR The value being assigned to ORE is a 


matrix or a higher-dimensional array but 
is not a singleton. 
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ljA -- Stop Action Osa 


The workspace-related system variable [sa specifies the 
action to be taken whenever execution stops for immediate 
execution input. 


Romain 


The domain for assignment to [SA is one of the 
following character vectors. 


"CLEAR" 
"EXIT" 
“OFF 


Superfluous leading and trailing blanks are ignored; an 
all-blank vector is treated as empty. 


The domain for [sa may be extended in the future. 
Default Value in a Clear Workspace 


In a clear workspace, the default value of OSA is an 
empty character vector (''). 


J$4-Dependent Primitive Functions 
No primitive functions depend upon the value of OSA. 
Effect 


The stop action specified is taken whenever execution 
stops for immediate execution input. The effect of each 
possible value of ISA is explained below. 

d No special stop action is taken. Execution 
suspends in the local environment and the 
System accepts immediate execution input. 


"CLEAR* The active workspace is cleared. 
RNIT" The state indicator is stripped back to an 
environment where [S4 is not 'EXIT'. Each 


level is displayed as it is stripped back. 
If the value of (SA in the resulting 
environment is 'CLEAR', the workspace is 
cleared. 


‘OFF! The APL session is terminated, with normal 
untying of any tied files. Control is 
returned to the DOS environment. The OFF 
value is specific to the APL«PLUS/PC System 
and may be absent in other APL«PLUS Systems. 


After the stop action has been taken, the system accepts 
immediate execution input. 
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If execution is interrupted at a point where [sa has 
been localized but not assigned, the state indicator is 
stripped back to an environment where []$4 is defined. 


Examples 


These examples show the effect of each of the settings 
of USA in the global environment. For the purpose of 
illustration, [SA is not localized in any of the functions 
called, and no other exception handlers are used. 


WSID 
IS 1 PROCESS 
3sI 
Osa+'' 
PROCESS ‘PAYROLL’ 
INDEX ERROR (An error occurs with L$4 set to 
LOOKUPLu]* its default value.) 
RH 
LOOKUPLu]« (Execution is suspended at the 
DSEARCH( 14) point of error.) 
xQr[8] 
PAYUPDATEL38] 
PROCESS[12] 
)RESET 
Dsr 
US4-'EXIT' (DSA is set to 'EXIT' in the global e 
PROCESS ‘PAYROLL’ environment and the function is 
INDEX ERROR executed again.) 
LooxuP( je (The error occurs again, 
PROCESS 'PAYROLL' 
^ 
esr ang the state indicator is 


cleared.) 


ÜSA-'CLEAR' o PROCESS 'PAYROLL' 
Osa is set to 'CLEAR' and the 
function is executed again.) 
INDEX ERROR 
LOOKUP[u 9 
CLEAR WS. . 


(The error occurs once more, but 
this time the entire active work- 
space is cleared.) 

WSID 
IS CLEAR WS 
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The folloving example illustrates another typical use 
of DSA., The function VALIDATE, executed when the workspace 
is loaded, checks to ensure that the user is authorized to 
use the workspace. If not, the workspace is cleared. 


v VALIDATE 
L1] + (GAZL1] e VALIDUSERLIST) p OK 
[2] — 'YOU ARE NOT AUTHORIZED TO USE THIS WORKSPACE.' 
[3] —'PLEASE CONTACT THE STEWARD FOR AUTHORIZATION.’ o +0 
[4] ox: Qsaer" 
v 


DLX«-'ÜSA-' 'CLEAR'* © VALIDATE! 
SAVE 


The following effect is then produced if an unauthorized 
user loads the workspace: 


LOAD TBATWS 
1 TRATWS SAVED. . . 
YOU ARE NOT AUTHORIZED TO USE THIS WORKSPACE. 
PLEASE CONTACT THE STEWARD FOR AUTHORIZATION. 


CLEAR WS... 

Error Reports 

DOMAIN ERROR The value being assigned to (Isa is a 
singleton or vector other than one of the 
allowed character vectors. 

RANK ERROR The value being assigned to [S4 is not a 


singleton or a vector. 
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DSES -- Memory Seament for Peeking and Poking DSEG 


The workspace-related system variable SEG specifies 
the memory segment in which the actions of []PEEK and [POKE 
shall be performed. SEG, as described here. is specific to 
the APL=PLUS/PC System; it may be different or absent in 
other APL«PLUS Systems. 

Domain 

The domain for assignment to 5$5EG is an empty vector or 
a singleton whose value is an integer between 32,768 and 
65,535 inclusive; values from 32768 through 65535 are used 
as equivalent to the values 32768 through ^1 respectively, 
and both are used as 65536|n. 


When USEG is referenced, its value is an empty vector 
or a scalar integer between 32,768 and 32,767 inclusive. 


Default Value in a Clear Workspace 


In a clear workspace, the default value for “|SEG is an 
empty numeric vector. 


JSEE-Dependent Primitive and System Functions 


No primitive functions depend on the value of DSEG. 
The value of USEG is used by OPEEK and IPOKE in the 
interpretation of their right arguments as memory locations 
(16xDSEG is added). 


Effect 


The effect of changing the value of DSEG is to change 
the memory location referenced by the right argument of 
PEEK and (POKE; the new value remains in effect until again 
Changed using _SEG. Also, the value when referenced 
changes. {PEEK and LPOKE reference the value of (SEG 
implicitly since that value (or for 10, the value it 
represents) is placed in the segment register when they 
begin to execute. This has the effect of adding sixteen 
times that value to the right argument JPEEK and jjPÓKE have 
been given to determine the actual memory location affected. 
Thus, the tvo expressions: 


DSEG + 10 o [JPEEK 1 
DSEG + 0 o [PEEK 161 


are equivalent. 
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The values most commonly of interest are 


LI 


720480 (equivalent to 45056) 


718532 (equivalent to 47104) 


o 


Examples 
ISEG 


DsEG- 20480 


Error Reports 
DOMAIN ERROR 


(the default) the 
start of the APL 
interpreter's data 
segment, which varies 
with the amount of 
memory configured, 
reserved, and so on 
the beginning of the 
monochrome monitor 
screen 

the beginning of the 
color monitor sceen 
the beginning of the DOS 
reserved area. 


(Note empty vector default.) 

(This leaves the DPOKE address of 0 
representing the first byte of the 
monochrome video screen memory.) 


The value being assigned to DSEG is a 


singleton whose value is not an empty 
vector nor an integer between 32,758 and 
inclusive, 


65 
LENGTH ERROR 


+535 


The value being assigned to (SEG is a 


vector, but of length greater than 1. 


RANK ERROR The value being assigned to DSEG is a 
matrix or a higher-dimensional array, but 
is not a singleton. 
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System Functions 


SI -- State Indi r Osr 


The niladic system function [SY returns a character 
matrix representation of the state indicator with one level 
of function call per row. 


sentes o 


result + (5I 
result - the explicit result 
Result 


The explicit result of [$1 is a character matrix 
containing essentially the same information as displayed by 
the )SI system command. The names of pendent or suspended 
functions, quad symbols (0), and hydrant symbols (2) may 
appear in the result. The keyword form equivalent 
characters are # for O and ^ for 2. Each row can contain 
one of the folloving: 


* @ quad symbol. indicating a pending evaluated input 
request 


* a hydrant symbol, indicating a pending statement 
invoked by the execute primitive function 


* a function name followed by a bracketed line number, 
indicating a pendent function o 


* a function name followed by a bracketed line number 
and a star, indicating a suspended function. 


If the state indicator is empty, the result of [SI is 
an empty matrix of shape 0 0. 


Example 
1 DSTOP 'TRI' o a*TRI 5" 
4 
rrrti] 
[00721 
TRI[1]* 


n 
2 


Error Report 


VS FULL The explicit result requires more 
workspace storage than is available. 
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INL => i r wi aliz OSINL 


The niladic system function (SINL returns a character 
matrix representation of the state indicator with one level 
of function call per rov, showing the names localized at 
each level. [ISIWL, as described here, is specific to the 
APL*PLUS/PC System; it may be different or absent in other 
APL*PLUS Systems. 


Syntax 
result + ÜSINL 
result - the explicit result 
Result 


The explicit result of DSINL is a character matrix 
containing essentially the same information as displayed by 
the )SINL system command. The names of pendent or suspended 
functions, quad symbols (C), and hydrant symbols (2) can 
appear in the result. The keyword form equivalent 
characters are # for D and ^ for s. Each row can contain 
one of the following: 


* a quad symbol, indicating a pending evaluated input 
request 


* a hydrant symbol, indicating a pending statement 
invoked by the execute primitive function 


* a function name followed by a bracketed line number, 
indicating a pendent function, and any localized 
names separated by blanks 

* a function name followed by a bracketed line number. 
a star (indicating a suspended function), and any 


localized names with a blank before and after each 
name, 


If the state indicator is empty, the result of DSINL is 
an empty matrix of shape 0 0. 


Example 
1 DSTOP 'TRIAL' o £'TRIAL 5' 


1 

TRIAL[I] 
pC«OSINL 

TRIAL[1]e 4 N DIO 

a 


217 
Error Report 
WS FULL The explicit result requires more 


workspace storage than is available. 
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DSIZE -- Space Us Identifier: OSI2E 


The monadic system function [SIZE returns the amount of 
Space used by a list of identifiers (names). 


Syntax 
result + [SIZE idlist 


result - the explicit result 
idlist - a list of identifiers 


Argument 


The argument contains a list of zero or more 
identifiers, which can be represented as one of the 
folloving: 


* a character singleton or vector containing one 
identifier 


* a character vector containing two or more 
identifiers with each pair separated by one or more 
blanks 


e a character matrix with one identifier in each row. 
Result 


The explicit result of []SIZE is a numeric vector. Each 
element is the amount of space (in bytes) required for the 
internal representation of the object named in the 
corresponding position of the argument. Symbol table space 
is not included. Zeros are returned for undefined 
identifiers, ill-formed names, and system functions and 
variables. A value of i6 is returned for function labels. 
L$IZE references the most local definition of each name. 


Example 
CSIZE ‘a TRI 

0 108 

Erxor Reports 

DOMAIN ERROR The argument has the proper rank but is 
not character-valued, 

RANK ERROR The argument is not a matrix, vector, or 
singleton. 

WS FULL The explicit result requires more 


workspace storage than is available. 
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USOUND -- Sound Pitches Osounp 


The monadic system function 2S0UND produces individual 
pitches for specified durations on the speaker of your 
personal computer. “SOUND, as described here. is specific 
to the APL«PLUS/PC System; it mày be different or absent in 
other APL*PLUS systems. 


Syntax 
-S0UND notes 


notes - a two-column integer matrix or two-element vector 
of paired pitches and durations 


Argument 


The argument to “souND is a two-column integer matrix 
with a row for each note selected, or a two-element vector 
for a single note. 


The first column contains the pitch of each note, 
expressed in vibrations per second (Hz) and ranging from 0 
through 32,767 inclusive, although computer speakers cannot 
produce nor human ears hear this wide frequency range. 

Thus, a pitch of 0 (no vibration) or any note too high to be 
heard can be used for silence (a musical rest). 


The second (right-hand) column contains the duration 
for each note, expressed in milliseconds (up to 65.535). 
However, note that the system clock used to time the sounds 
may have much less resolution than one-thousandth of a 
second. For example, the clock in the IBM Personal 
Computer, and in others similar to it, ticks 18.2 times per 
second. 


The system function [SOUND does not return an explicit 
result. 


Effect 


The specified notes selected by the values of the left- 
and right-hand columns of the argument are played. 


Up to 32 notes can be buffered and played while 
Subsequent APL expressions are being entered or executed. 
Longer sequences do not return control until the remaining 
number of notes is small enough to be buffered. 


Any note received in the sound buffer with a duration 
of 0 halts further playing and clears the sound buffer cf 
any remaining notes. This can also be done with Exit or a 
strong interrupt (a double BREAK). 
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Examples 


[SOUND 3 20256 250 0 500 512 125 (Play middle-C for a 
quarter of a second, 
à half second of 
silence, followed by e 
high-C for an eighth 
of a second.) 


$«1256»2*0,*1120*12 

OUND S,[1.5] 200 (Play a vell- 
tempered 13-note 
scale from niddle 
through high-C for a 
fifth of a second 
per tone.) 


ISOUND 0 0 (Stop tune being 
Played as soon as 
this sound enters 
the sound buffer.) 


Error Reports 


DOMAIN ERROR The argument contains character data, 
floating point data, or the first column 
has values outside the range 0 through 
32,767, or the second column has values 
outside the range 32,788 to 65,535. o 


LENGTE ERROR The matrix argument has the wrong number 
of columns. 


RANX ERROR The argument is not a matrix or vector. 
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Iss String Search Oss 


The dyadic system function JSS performs a string 
search, locating all occurrences of a character scalar or 
vector within another character vector. 


ntax 


result + data OSS pattern 


result - the explicit result 
data - the character vector to be searched 
Pattern - the character vector or scalar to be located in 


Arguments 


The left argument (data) and the right argument 
(pattern) must be character vectors or scalar. 


Result 


The explicit result of GSS is a Boolean vector of the 
same length as the left argument, showing the location of 
all occurrences of the right argument within the left 
argument. A one in the result signifies a match beginning 
at that position within the left argument. All matches are 
shown, including overlapping ones. An empty right argument 
is matched at every location within the left argument. 


Examples 
'MISSISSIPPI' JSS ‘ISSI’ 
01001000000 


‘EMPTY VECTOR MATCHES ALL POINTS’ (SS '' 
EEIE Aa WE a dd 4 a ea 


CVe'THIS IS T00 SPACED O0UT.' o (-CV DSS ' "CV 


THIS IS TOO SPACED OUT. 


Error Reports 

DOMAIN ERROR One of the arguments is not 
character-valued. 

RANK ERROR One of the arguments is neither a vector 
nor a singleton. 

WS FULL The explicit result requires more 


workspace storage than is available. 
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DSTOP -- Stop Function Execution UsroP 


The system function OSTOP sets, removes, or reports 
flags on specified lines of a user-defined function. 
Execution of the user-defined function halts just before any 
of the flagged lines it reaches. allowing examination and 
adjustment of the local environment. 


+ 5STOP fnname 
+ linenums [STOP fnname 


- the explicit result 

nums - a vector or singleton of integer line numbers 
before which to stop function execution 

fnname - a character vector or singleton containing the 

function's name 


The optional left argument is an integer vector or 
singleton containing the lines of the function named in the 
right argument before which flags should be set. Zero and 
integers which are not line numbers in the specified 
function are ignored in the APL«PLUS/PC System. 


The right argument is a character vector or singleton 
containing the name of an unlocked function in the 
workspace. 


Result 


The explicit result of CSTOP is an integer vector of 
the lines of the specified function for which prior stops 
were set. 


Effect 


The effect of DSTOP is to halt subsequent executions of 
the function immediately prior to executing the lines 
specified in the left argument (linenums). It also removes 
any existing stop settings from other lines in the function 
which are not included in the argument. Thus, in the 
APL*PLUS/PC System, any of the three expressions: 


(10) DSTOP fnname 
'' DSTOP fnname 
e DSTOP fnname 


will remove all stop settings from the function in the 
active workspace. 
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Each time function execution reaches a line that has 
been set to stop, execution is halted, and the system enters 
immediate execution mode, preserving the state indicator and 
all local values and definitions. You can then explore and 
even alter the local environment before branching (+) back 
into or out of the suspended function. The resulting 
ability to observe and alter the local environment at those 
Chosen points in function execution is a valuable aid for 
debugging a program. 


Stop settings are saved and reloaded vith a workspace, 
but are not copied along with the particular function to 
which they apply (by (copy, )COPY, [JPCOPY. or )PCOPY). 
Redefining a function with either DEDIT or )EDIT removes all 
stop settings from that function. Editing a function line 
with either v or DDEFL removes any setting associated with 
that line of code. If other lines are inserted or deleted 
before a line, the setting moves vith the line of code. 
Locking a function either by 9 or [LOCK removes all stop 
settings in the function. 


Example 
Given a function: 
V ReFIBONACCI N 
Ret i 


(1) 
[2] BACK: ReR,+/—2tR 
[3) — +BACKxN>pR 


(13) ODSTOP 'FIBONACCI' 
(Empty explicit result means no lines were 
previously set.) 


FIBONACCI 12 
FIBONACCIÓ1] 
R 


VALUE ERROR 
R 
T 
FIBONACCI(2} 
R 
Fi 
+2 
PIBONACCILS] 
R 
112 
Dsr 
FIBONACCIL3]« 
Dic 
3 
-DLC 
FIBONACCIL2] 
R 
a ae? 
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Error Reports 


DOMAIN ERROR The right argument is not the name of an 
unlocked function in the workspace, or the 
left argument is not integer-valued. 


RANK ERROR Either argument is not a vector or a o 
singleton. 
WS FULL The explicit result requires more 


workspace storage than is available. 
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[SZPTR -- Symbol Table Pointer to APL Objects in DsTPTR 
the Workspace 


The monadic system function ÜSTPTR returns a pointer to 
8 valve, indicating the beginning of the internal storage 
Currently being used by the most local definitions of a list 
of identifiers (names) in the active workspace. [STPTR, as 
described here, is specific to the APL*PLUS/PC System; it 
may be different or absent in other APL«PLUS systems. 


Syntax 
result + CSTPTR idlist 


result - the explicit result 
idlist - a list of identifiers 


Argument 


The argument contains a list of zero or more 
identifiers. It can be represented as one of the following: 


* a character scalar or vector containing one 
identifier 


* a8 character vector containing two or more 
identifiers with each pair separated by one or more 
blanks 


* a character matrix with one identifier in each rov. 


Result 


The explicit result of '$TPTR is a numeric vector, with 
one eiement for each identifier in the argument. 


Each element of the result is either a zero if no such 
object was found or if the name was ill-formed, or is the 
address (in the interpreter data segment) that contains the 
address of the current internal storage location of that 
object if found. 


1f the object does not exist in the symbol table (that 
is, if it has never been referenced), [ISTPTR returns 0. If 
the object exists in the symbol table but is undefined, 
ÜSTPTR returns a non-zero address, but the word of data at 
this address is 0. If the object is a label, the word of 
data at this address is the current value of the label. 


Effect 


Objects in the workspace are stored on CPU memory 
paragraph boundaries. Objects are normally addressed with a 
segment address register. (S7P7TR returns the offset (in the 
interpreter data segment) of a location that contains the 
segment address of the actual object. The segment address 
of the object is usually given by: 
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EG-10 o 256LCPEEK 1 O^DSTPTR 'OBJECT' 


provided that the execution of this statement does not 
trigger a workspace compaction (garbage collection). A 
garbage collection can be forced just before executing the 
above statements by executing: 


0 Op-WA 


To pass an object in the workspace to a user-written 
machine-language routine invoked by L[CALL. execute: 


(0, OSTPTR 'object') {CALL code 

and begin the "code" routine with the instruction: 
MOV ES, (BX) 

The E$ register will now be addressing the object. 


When ES addresses a variable in the workspace, £S:6 
contains the number of bytes in each element of the array 
(1, 2, or 8, depending on datatype).  ES:7 contains the rank 
of the array, and the lengths along each dimension (if any) 
begin at ES:8. The dimensions are stored as two-byte 
integers. The actual data in the array begins immediately 
after the last dimension. The first six bytes of the 
object's segment contain pointers used by the interpreter's 
workspace management routines. 


Note that a garbage collection will cause many or all 
objects in the workspace to move. This will not change the 
value returned by [STPTR, but it may cause the segment 
address contained in the location pointed to by “STPTR to 
change. 


Stored values returned by OSTPTR should be recalculated 
each time a workspace is loaded, since the values can vary 
from one session to another. 


Examples 


USTPTR ‘DATA ANSWER ' 
16907 17021 


(0, ISTPTR 'DATA') CALL CODE (Passes DATA to 
machine language 
subroutine CODE 
which must begin 
with the instruction 
MOV ES,.[BX), since 
the ES register then 
addresses the 
variable DATA.) 


Also see the examples for "CALL -- Call Machine Language 
Routine". 
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Error Reports 
DOMAIN ERROR 


RANK ERROR 


WS FULL 


The argument has the proper rank but is 
not character valued or the argunent 
specifies a locked function. 


The argument is not a matrix, vector, or 
singleton, 


The explicit result requires more work- 
space storage than is available. 
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USYMB 


Workspace Symbols DSYMB 


The niladic system function DSYM8 returns the current 
number of symbol table entries in the active vorkspace. 


sase e 


result + CSYMB 
result - the explicit result 
Result 


The explicit result of [JSYMB is a two-element numeric 
vector. The first element is the number of entries reserved 
in the symbol table of the active workspace; the second 
element is the number of entries already used in the symbol 
table of the active vorkspace. The size of the symbol table 
in a clear workspace can be altered by the system command 
)SYMBOLS to values from 1 to 2,048 (see "System Commands" in 


Example 
CLEAR 
CLEAR WS . 
ŪSYNB 
512 0 


ac e 


WS FULL The explicit result requires more 
workspace storage than is available. 
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3SY3ID 


The system constant [|$YSID returns the identification 
of the APL*PLUS System being used. 


Syntax 
result + USYSID 
result - the explicit result 
Result 


The explicit result of “SYSID is a character vector 
containing the identification of the APL*PLUS System being 
used. All characters are used to identify a system. 


Example 
SYSID 
APL*PLUSÍPC VERSION 5.0 
Error Report 
WS FULL The explicit result requires more 


workspace storage than is available. 
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È Terminal Control Drc 


The system constant [C returns a backspace, a newline, 
and a linefeed as a three-character vector. 


Syntax 
result + Orc 
result - the explicit result 
Result 


The explicit result of JTC is a character vector 
containing three special characters: backspace, newline, 
and linefeed. These are transmitted to remote devices as 
ASCII BS, CR, and LF (decimal 8, 13 and 10). 


Effect 


Each element of the explicit result of DTC produces its 
own effect. 


The first element of the explicit result is identical 
to DTCBS and, when displayed on the screen, has the same 
effect of moving the cursor one position to the left. 
Overstriking may or may not be performed, controlled by a 
JPOKE. Its effect when transmitted to remote devices, 
including printers and modems, varies with the device. 


The second element of the explicit result of [7C is 
identical to DTCNL and has the same effect of moving the 
cursor to the leftmost column of the folloving line on 
either the screen or a printer. 


The third element of the explicit result of UTC is 
identical to [TCLF; on the APL*PLUS/PC System it moves the 
Cursor down one line in the same column on the screen, but 
the effect on remote devices depends on the device. See the 
discussion under [ITCLF. 


Exanple 
* NOV * .OTC 1],  DORN* ,5TCU2], "WE! .DTCU8 ], *60 ." 
NODOWN 
WE 
Go. 
Error Report 
WS FULL The explicit result requires more 


workspace storage than is available. 
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ITCBEL -- Terminal Control, Bell DTCBEL 


The system constant []TCBEL returns a bell character. 
Syntax 
result + [ITCBEL 
result - the explicit result 


Result 


The explicit result of DTCBEL is a character scalar of 
the ASCII BEL character, represented on your personal 
computer by a single chirp. It is transmitted to remote 
devices as an ASCII BEL (decimal 7). 


Effect 


When JTCBEL is used with a remote device, it activates 
the audible alarm by transmitting an ASCII BEL character 
(Ctrl G). On many remote devices this results in a "beep" 
or a bell sound. 


NOTE: The sound produced by the BEL control code vill 
last more than one character-time (for example, 1/30th of a 
second at 30 CPS); thus, several bell characters may need to 
be separated by one or more null characters ([TCNUL) in 
Order to be heard as distinct sounds. 


You can use a [POKE to turn the computer's speaker on 
or off, activating and silencing the chirp from a remote 
device. 


Example 
TASK © 3 [MRBIN [TCBEL (Ring the louder BEL 
on the parallel 
printer to signal 
TASK completion.) 
Error Report 
WS PULL The explicit result requires more 


workspace storage than is available. 
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UTCBS -- Terminal Control, Backspace Orces 


The system constant []TCBS returns a backspace 
character. 


Syntax 

result + Orcas 

result - the explicit result 

Result 

The explicit result of JrcBs is a character scalar 
containing a backspace character. It is transmitted to 
remote devices as an ASCII BS (decimal 8). 
Effect 

When displayed on the screen, []TCBS moves the cursor 
one position to the left. Overstriking may or may not be 
performed, controlled by a []POKE. 
Example 


tiap’ '),'A' ,ESoDTCBS) ,'B* 
Boa 


Error Report 


WS FULL The explicit result requires more 
workspace storage than is available. 


Copyright 1983 STSC, Inc. 3-270 System Functions 


LTCDEL -- Terminal Control. Delete ITCDEL 

The system constant JTCDEL returns a delete character. 
Syntax 

result + ÜTCDEL o 

result - the explicit result 

Result 

The explicit result of [TCDEL is a character scalar of 
a DELETE character. It is transmitted to remote devices as 
an ASCII DEL (decimal 127). 
Effect 

ZLTCDEL does not move the cursor, but causes a pause in 
output for one character-time (for example, 1/30th of a 
second on a 30 CPS device, 1/960th of a second on a 960 CPS 
device). For screen output, the pause is approximately .001 


seconds. JTCDEL is transmitted in communications as an 
ASCII DEL character. 


Example 
A+ "DOWN? ,DTCDEL , 'WE' ,ÜTCDEL, 'G0.' 


pA 
: e 


4 
DOWNWEGO. 

als 933 
we 


Error Report 


WS FULL The explicit result requires more 
workspace storage than is available. 
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ntrol, E: ürcEsc 


The system constant [TCESC returns an escape character. 
DTCESC, as described here, is specific to the APL*PLUS/PC 
System; it may be different or absent in other APL*PLUS 
Systems. 


Syntax 
result + DTCESC 
result - the explicit result 
Result 
The explicit result of [ITCESC is a character scalar of 
an escape character. The explicit result of DTCESC can be 
catenated to other characters and stored in variables. It 


is transmitted to remote devices as an ASCII ESC (decimal 
27). 


Effect 


When [ICESC is transmitted to the screen, no character 
is displayed but a pause of approximately .001 seconds 
Occurs. When transmitted to various remote devices (such as 
multi-pen plotters or certain printers). it signals to them 
that the character(s) which follow are to be interpreted as 
special instructions, not simply as part of the data. 


Error Report 


WS FULL The explicit result requires more 
workspace storage than is available. 
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ITCEF. 


Term 


control, Form, Orerr 
The system constant [?CFF returns a form feed 


character. (OTCFF, as described here, is specific to the 
APL*PLUS/PC System; it may be different or absent in other 


APL*PLUS Systems. e 


Syntax 

result + ÜTCFF 

result - the explicit result 

Result 

The explicit result of [TCFF is a character scalar of a 
form feed character. It is transmitted to remote devices as 
an ASCII FF (decimal 12). 
Effect 

DTCFF clears the current window (unprotected area) when 
transmitted to the screen, and leaves the cursor in the 
upper-left corner of the window. When [ITCFF is transmitted 
to certain hardcopy printers or terminals, the paper is 
rolled forward to the top of a new page (form feed). 
Error Report 


WS FULL The explicit result requires more e 
workspace storage than is available. 
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ITCLF -- Terminal Control, Linefeed ÜrcirF 


The system constant 7TCLF returns a linefeed character. 


Syntax 
result + DTCLF 
result - the explicit result 
Result 


The explicit result of ITCLF is a character scalar of a 
linefeed character. It is transmitted to remote devices as 
an ASCII LF (decimal 10). 


Effect 


The effect of DTCLF varies with the device to which it 
is directed. When displayed on the personal computer screen 
or certain terminals and printers, this character causes the 
paper or screen to roll up one line or the cursor to move 
down one line, while keeping the cursor in the same column 
position as on the previous line. On terminals or printers, 
however, it may be treated as a DTCNL, or ignored 
completely. On some devices, it may also print faster than 
DTCNL when skipping multiple lines. 


Example 


A+‘ DOWN" ,[,ITCLF ," VE' ,JTCLF ,' G0." 
pA 


Error Repor 


WS FULL The explicit result requires more 
workspace storage than is available. 
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CNL -- Terminal Control, New Line ÜrCNL 


The system constant CTCNL returns a newline character. 


Syntax 
result + (UTCNL e 


result - the explicit result 
Result 


The explicit result of [TCNL is a character scalar of a 
nevline character. It is transmitted to remote devices as 
an ASCII CR (decimal 13). 


Effect 


When displayed on the screen or on a printer, DTCNL 
moves the cursor to the first column of the next line. The 
newline character cannot be entered from the keyboard into a 
Character constant (between quotes) because it ends a line 
of input (thus, the closing quote cannot follow it). 


Example 
Ax" DOWN" ,DTCNL, 'WE* ,DTCNL,' G0." 
pa 
1 
A 
DOWN 
WE 
Go. 
Error Report 
WS FULL The explicit result requires more 


workspace storage than is available. 
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DTCNUL -- Terminal Control, Null DTCNUL 

The system constant DTCNUL returns a null character. 
Syntax 

result + ÜTCNUL 

result - the explicit result 

Result 

The explicit result of DTCNUL is a character scalar of 
a null character, It is transmitted to remote devices as an 
ASCII NUL (decimal 0). 


Effect 


ÜTCHUL does not move the cursor, but causes a pause in 
output for one character-time (for example, 1/30th of a 
second on a 30 CPS device, 1/960th of a second on a 960 CPS 
device). 


Example 
Ac DOVN* ,OTCHUL,'WE' ,LTCNUL, G0." 
pA 
43 
4 
DOWNWEGO. 
A[5 9] 
we 
Error Report 
WS FULL The explicit result requires more 


workspace storage than is available. 
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[TRACE -- Trace Function Execution Orrace 


The system function ITRACE permits the user to observe 
the progress of specified lines of function execution as a 
debugging aid, or to determine which lines are flagged to be 
observed. 


Syntax 
result + — ZTRACE Ínname 
result + linenums LTRACE inname 
result - the explicit result 
linenums - a vector or singleton of integer line numbers 
to trace 
foname - a character vector or singleton containing the 
function's name 
Arguments 


The optional left argument is an integer vector or 
singleton indicating which lines of the function named in 
the right argument are to be traced. They will continue to 
be traced until a later execution of J7RACE on the function 
name in this workspace resets the lines. Zero and integers 
which are not line numbers in the specified function are 
ignored in the APL*PLUS/PC System. 


The right argument is a character vector or singleton 
Containing the name of an unlocked function in the 
workspace. 


Result 


The explicit result of [TRACE is an integer vector of 
the lines of the specified function for which tracing was in 
effect until this execution of (TRACE. 


Effect 


The effect of DTRACE is to flag all the lines of the 
function specified in the left argument (linenums) so the 
lines can be traced. It also removes any existing tracing 
from other lines in the function which are not included in 
the argument. Thus, in the APL*PLUS/PC System, any of the 
following three expressions: 


(10) D7RACE fnname 
*' Drrace Ínname 
e (TRACE fnname 


will remove all tracing from the function in the active 
workspace. 
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During execution of a function that is being traced, 
the system displays the final value calculated in each 
Statement on each traced line. The value appears after the 
function's name and the bracketed line number, or after a o. 
This is true even for values that would not display in 
normal (untraced) execution. In the case of a branch in the 
function, a + is displayed before the value to which it 
branched. 


The resulting ability to observe the sequence in which 
the lines are executed and the internal values (those not 
normally displayed) is a valuable aid in debugging a 
program. 


Trace settings are saved and reloaded vith a workspace, 
but are not copied along vith the particular function to 
which they apply (by (copy, )COPY, ÜPCOPY, or )PCOPY). 
Redefining a function with either DEDIT or )EDIT removes all 
trace setting from that function. Editing a function line 
with either ¥ or [DEFL removes any setting associated with 
that line of code. If other lines are inserted or deleted 
before a line, the setting moves with the line of code. 
Locking a function with either * or [LOCK removes all trace 
settings in that function. 


Example 


V RESULT + GO 
(1) Q+'WEW LINE DURING TRACE DESPITE THE [) OUTPUT!' 
[2] RESULT + 1 
[3) LABEL: RESULT + (O,RESULT)*RESULT,O © + LABEL x 4 > ORESULT 
v 


(5) DTRACE ‘Go 
(An empty explicit result means no lines 
were set.) 


GO[1]NEW LINE DURING TRACE DESPITE THE "5 OUTPUT! 
G0[2)1 

c0[3)1 1 

043 

60(3]11 2 1 

043 

60[311 331 

920 

1331 (The explicit result of 60.) 


Error Reports 
DOMAIN ERROR The right argument is not the name of an 


unlocked function in the workspace, or the 
left argument is not integer-valued. 
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RANK ERROR Either argument is not a vector or a 


singleton. 
WS FULL The explicit result requires more space 
than is available in the workspace. 
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System Functions 


Ors -- Current Timestamp ürs 
The niladic system function Ors returns the current 


date and time of day as represented by the personal 
computer's internal clock. 


Syntax 
result + Ors 
result - the explicit result 
Result 


The explicit result of JS is a seven-element numeric 
vector containing the following information: 


[1] Year 

[2] Month 

[3] Day 

[4] Hour 

[5] Minute 

[6] Second 

[7] Millisecond 


The seventh element of the result is expressed in 
milliseconds for consistency with other APL*PLUS Systems, 
however the personal computer's system clock precision 
determines the useful precision of any time measurements. 


Ors relies on the system clock maintained by DOS for 
its time measurement. These values are drawn from the 
system clock maintained by DOS, which reports them in 
centiseconds. Many personal computer systems have clocks 
that cannot measure time intervals shorter than 1/20 or 1/60 
of a second because the clock does not "tick" (change value) 
more frequently. The clock in the IBM Personal Computer, 
and in others similar to it, ticks 18.2 times per second. 
Refer to your computer manufacturer's manual for the 
precision of your system clock. 


The result of JTS may differ from the exact time of 
day, but should be no more than a fev seconds from the time 
according to the last setting or resetting of the system 
clock. 


The first three elements in the result of [TS always 


indicate a date, and the last four elements always indicate 
atime of less than 24 hours. 


Example 


Ors 
1985 9 8 19 12 7 240 
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Error Report 


WS FULL The explicit result requires more 
workspace storage than is available. 
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DUL -- User Load UL 


The system constant DUL returns a 1. [UZ exists in the 
APL*PLUS/PC System for compatibility with other APL*PLUS 
Systems, so that programs brought in from such systems can 
be executed without modification. 


Syntax 
result + JUL 
result - the explicit result 
Result 


The explicit result of [UL is a numeric scalar 1. 


Error Report 


WS FULL The explicit result requires more 
workspace storage than is available. 
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WI 


Verification of Input For! Or 
The monadic system function []/7 can be used in 


conjunction with [FI to provide a validity check on the 
input character vector. 


E] Syntax 
result + DVI data 
result - the explicit result 


data - character data 
Argument 
The argument is a singleton or vector of character 
data. 
Result 


The explicit result of (WI is a Boolean vector with 1's 
in the positions where groups of characters represent 
well-formed numbers and 0's where they do not. 


Examples 
A*'666 71.20 .1 3141598 5* 
GEI 4 


666 71.2 0.1 3.14158 
e QVI 4 
1111 


DEI ‘ANSWER: 666* 


0 666 
B-'ANSWER IS 666 LBS." 
DFI B5 
0 0 666 0 
DVI B 
0010 
(D77 B)/DFI 8 
666 
C+" .25 -6.25 8,9,10' 
Uer c 
0.25 0 Q 
Ove 
100 
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As suggested by the last example. a minus sign (-) 
cannot be used in place of a negative sign ( ) to negate a 
number; and commas and other symbols do not serve to 
separate fields. An example of a technique for modifying 
such symbols to form a valid argument for FI is 


EXT-' 0123456789F 
INT-' 0123456789F, ^ *" 
LY INT[EXTi' .25 -6.25 8.9.10'] 
0.25 6.25 8 9 10 


Error Reports 


DOMAIN ERROR The argument is not character-valued. 
RANK ERROR The argument is not a vector or singleton, 
WS FULL The explicit result requires more 

workspace storage than is available. 
Use of FI vith ZKI 


The expression (VI data)/J]FI data returns the values 
from well-formed fields in the character vector data and 
ignores the others. 


While [FY and “vz can be used directly (as shown in the 
above examples), they are used to greater advantage within 
an APL function that is tailored to control keyboard input 
for an entire application. Such an APL function can be made 
responsible for converting minus signs and other symbols, 
validating input fields, and performing other checks. For 
example, the function INCÓN shown below takes as its 
argument the number of fields to be entered from the 
keyboard and returns the values of the fields as a numeric 
vector. INCON accepts commas or blanks between successive 
numbers, and minus or negative signs. It prompts and checks 
for the correct number of input values. 


vOZeINCON XiYilNTiEXT; 


[1]  EXT«' 0123556789E.,- " 

[2]  INT«' 0123856789E. “es! 

i3) — ERR-O 

[4] LI:(ERR/'BAD INPUT.  '),'ENTER '.(YX),' NUMBER',(X=1)4'5:' 


[5]  YeINT[EXTi7] o Z-—FI Y 
[61] ERR+(X#pZ)v~a/QWI Y o +ERR/L1 
v 


Using a function like INCON for input throughout an 
application helps keep rules for data entry simple and 
uniform. 
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DER -- visual Representation of a Function Dra 


The monadic system function OVR returns the visual 
representation of the most local definition of a function as 
a character vector. 


Syntax 
result + DYR fnname 


resylt - the explicit result 
fnname - the function name 


Argument 


The argument to [YR is the character representation of 
one function name. It can be represented as a character 
scalar or vector, 


Result 


The explicit result of [V is a character vector. It 
constitutes a visual representation of the function, with 
bracketed line numbers ànd embedded nevline characters 
separating the character representations of the successive 
lines of the function. The explicit result is not affected 
by Dry. 


1f the argument is a character singleton or vector but 


Goes not contain the name of an unlocked function, the 
result is an empty vector. 


Example 


bQ-DVR 'TRI' 
72 


(21 — -(«p4)/0 9 DcA«(0,4)*4,0 o *DLC 
Li 


Error Reports 

DOMAIN ERROR The argument has the proper rank but is 
not character-valued. 

RANK ERROR The argument is not a vector or scalar. 

WS FULL The explicit result requires more 


workspace storage than is available. 
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X4 -- Work Area Available Wa 


The niladic system function [wa returns the current 
amount of work area available in the active workspace (in 
bytes). 


— © 


result - the explicit result 


Besult 


The explicit result of CW4 is a numeric scalar whose 
value is the current number of unused bytes in the active 
workspace. 


)WSID 
IS 1 OFFICE 

Wa 
14372 


Error Report 


WS FULL The explicit result requires more 
workspace storage than is available. e 
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WGET -- Get Window Data ONGET 


The ambivalent system function CWGET reads the 
characters or attributes or both from a specified (or from 
the current) screen window. (WGET, as described here, is 
specific to the APL«PLUS/PC System; it may be different or 
absent in other APL*PLUS Systems. 


Syntax 


result + DWGET rtype 
result + wspec OWGET rtype 


result - the explicit result 

wspec - optional specification of a window other than 
the current one 

rtype - the type of result desired, an integer from 1 to 
4 inclusive 


Arguments 


The optional left argument is a specification of a 
window to be used during this one operation, and has the 
same effect as setting [WINDOW before the operation and 
resetting it after the operation. If there is no left 
argument, the current window is used. 


The right argument to CWGET is an integer 1 through 4. 
1t can be a singleton of any rank. It specifies the type of 
explicit result desired as one of the following: 


1 a character matrix containing the characters visible 
in the window (without their display attributes) 


2 an integer matrix containing the attribute values 
associated with each character position in the 
window (the attribute values are given in the table 
below) 


3 a rank 3 character array where result{;;1] contains 
the characters displayed on the screen (the same as 
the result if rtype-1; result[;;2] contains the 
attributes coded as characters by DaV[att + DI01 
where att is the same as the integer result when 
rtype-2) 

4 result is a numeric matrix in which each element 
contains both the screen character and the screen 
attribute for one character position combined in 
this vay: 


256 4 attribute, ([A:character) - (70 
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Result 


The explicit result of [WGET is the data requested by 
the specified rtype from the specified window, as a matrix 
(or for result type 3, a three-dimensional array with last 


coordinate of length 2). e 


Attribute Values for Monochrome Screen 


0 non-display 
1 underline 
7 white character/black background 
3 underline, high intensity 
15 white character/black background, high intensity 
112 reverse video 
120 reverse video, high intensity 
129 underline, blinking 
135 white character/black background, blinking 
137 underline, high intensity, blinking 
143 white char/black background, high intensity. blinking 
240 reverse video, blinking 
248 reverse video, high intensity, blinking 


Other values are possible, but on a monochrome display 
they merely duplicate these effects (see your computer 
manufacturer's manual for more information). 


The attribute values used with [WGET are, by default, 
interpreted as IBM-specific, but can be set to 
interpretation as generic attribute values by JPOKE. e 


neri ribi Val 


9 = normal 
1 = inverse video 
2 = high intensity 
4 = blinking 

8 = underscored 


Any combination of the non-zero attributes can be 
represented by using the sum of the values for those 
attributes when generic attributes are in effect, Functions 
using these values can run unaltered on varied hardware 
where the native attribute values are different. 


NOTE: If the SPOKE is changed during an APL session, 
attributes read from the screen earlier in the 
session with [WGET may change if they are later 
restored with [WPUT. In addition, imperfect mapping 
between generic and IBM-specific values may cause 
different attributes to occur. 
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When the generic attributes are not in use, the 
following IBM-specific values prevail: 


Attribute Values for Character Color Screen 


attribute 


or, 
attribute 


colors: 


o 
1 
2 
3 
4 
5 
6 
7 


+ ( 16 x 
+i 8 
+ (128 x 


x 


28284 


black 
blue 
green 
cyan 
red 
magenta 
yellow 
white 


foregroundcolor 
backgroundcolor ) 
intense ) 
blinking ) 


blink ,background, 
intense, foreground 


Notes: White background with black foreground is reverse 


video. 


Black on black is invisible (like monochrome 
non-display). 
White on white gives white on black. 
Grey is low-intensity white. 

Brown is low-intensity yellow. 


Effect 


The function of DWGET is to change the window setting 
temporarily if a left argument is given, return the explicit 
result from within that window, and restore the window 
Setting in use before executing DWGET. 


Examples 


TOP + 0 0 1 80 [WGET 1 


(Obtain the characters on 
the top row of the 
screen.) 


SCREEN + 0 0 25 80 [WGET 3 (Save the entire screen 


W + ÜWGET 2 


including its current 
attributes.) 


(Obtain the attributes of 
the current window.) 


3 D[ARBIN DTCNL, 0 0 7 80 “WGET 1 
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(Print top seven lines 
from the screen.) 


3-288 System Functions 


Error Reports 


DOMAIN ERROR A left argument is present, but not in the 
domain of [WINDOW; or, the right argument 
is not one of the values 1, 2. 3. or 4. 


LENGTH ERROR The right argument is a vector, but not a o 
singleton; or the left argument is a 
vector, but does not have four elements. 


RANK ERROR The left argument is present, but is not a 
vector; the right argument has a rank 
higher than 1, but is not a singleton. 


WS FULL The explicit result requires more 
workspace storage than is available. 
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IWIN -- Windowed Input Control WIN 


The ambivalent system function [WIN limits keyboard 
input to specified windows (fields) on the screen, and 
accepts only specified keystrokes within each field. Used 
with OWPUT, OWKEY, and [WGET, [WIN provides efficient 
forms-style input. WIN is experimental in this release of 
the APL*PLUS/PC System; it may be different, absent, or 
replaced by an entirely different feature in a subsequent 
release. 


Syntax 


result + (wry fields 
result + behavior [WIN fields 


- the explicit result 

- optional integer singleton or vector of up to 
four elements 

- integer vector or matrix describing the 
windows and their behavior (field type) 


The optional left argument to [WIN is an integer 
Singleton or vector of up to four elements. These elements 
specify behavior once in [WIN input mode. If less than four 
elements are present, the default values apply for the 
remaining positions. 


The elements of the left argument represent: 


[$$] the active field upon entry (depends on DIO), 
default value = (70, the first field listed in 
the right argument 


[2 3] the cursor position within that field, default 
value = 0 0, the beginning of the field 


[5] the timeout between keystrokes, in seconds, or, 
1 (the default) meaning no timeout. 


The right argument to [WIN is an integer matrix (or 
vector) where each row describes the location of one vindow 
on the screen and the keystroke sets the user can use to 
modify the contents of that windov. The list of fields 
described by the rows of the matrix is circular; that is, by 
advancing from the last field, you enter the first field. 
The matrix has 4 to 8 columns defined as follows: 


columns 1-4 the window specification delimiting the 
field 


column 5 integer denoting field type (like 
"numeric") 
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column 6 special feature selection (sum of code 


values) 
column 7 display attribute for this field when 
active 
column 8 display attribute for this field when 
inactive 


The window specification is of the same form as values for 
UWINDOW: the number of rows and columns to skip from the 
upper left-hand corner of the screen to locate the upper 
left-hand corner of the windov, followed by the shape 
(number of rows and columns) of the window. 


The field type is an integer indicating the type of the 
specified field. The value must be 0, 1, or a power of 2 
from 1 (2*0) through 16384 (214%) inclusive. 1 acts as a 
combined field type accepting any keystroke permitted in any 
of the defined field types. These field types (except for 
0) can be user-defined. A field type is defined by the 
keystrokes that are allowed in it. This is determined by 
IWKEY. The default field types when .WKEY has not been used 
are 


0 - restricted (no displayable characters) 

1 - unrestricted (any displayable characters, like fj 
accepted) 

2 - numeric only (only characters "0123256789.,- E"). 


Note that field types for 2*2 through 2*14 are always 
user-defined. 


Special feature selection is a sum of a subset of the 
following code values which are used to select those 
features: 


1 - autotab to next field after filling last position 

? - check for valid numbers upon attempt to leave this 
field 

a - refuse to leave this field until number is valid 

8 - exit from [WIN on attempt to overfill this field 

6 - exit from [WIN for any invalid keystroke in this 

field 

32 - exit from [WIN for validation upon attempt to leave 

this field. 


By default (if the right argument has less than six 
columns), only the first of the following features is 
selected. 


1 autotab is the automatic movement from a filled 
field into the next field without a special 
keystroke (like Tab). This feature is the default 
Selection if the right argument has less than síx 
columns. 


Copyright 1983 STSC, Inc. 3-288.3 System Functions 


2 checking for valid numbers uses the same criteria as 
DWI to check for exactly one valid number on each 
line of the field when any attempt is made to leave 
the field. If the number is not valid, and feature 
4 is not also selected, [WIN terminates, returning a 
1 as the first element of its result. 


4 refusing to leave this field until a number is valid 
requires that feature 2 also be selected. Attempts 
to leave the field vithout a valid number on each 
line result only in a beep. 


8 exit upon overfill overrides the default beep and 
terminates (WIN, A 2 appears as the first element 
in the result if a character is entered which would 
either replace the last character in the field or, 
by insertion, push a character out of the field. 


16 exit on any invalid keystroke overrides the default 
beep when encountering a keystroke not acceptable in 
this field type, and forces an exit from [WIN with a 
3 as the first element of the result. 


32 exit for validation terminates (WIN with 4 as the 
first element of the result when the user types a 
keystroke that would move to a different field. 
Using this option makes it possible for an 
application to call an APL function that checks the 
contents of the field for validity and provides 
immediate user feedback. Once the field has been 
validated, [IWIN can be resumed after the user's 
existing keystroke has been placed in the type-ahead 
buffer with [INBUF. 


The display attributes for the active and inactive fields 
are in the same numeric codes used for [WPUT, and are 
interpreted as generic or IBM-specific using the same l]PEEK 
as WPUT does. If either or both of these columns are 
omitted from the argument, no change from the displayed 
attribute occurs. 


Result 


The explicit result of [WIN is an integer vector, The 
elements represent: 


[1] type of exit from IWIN, where: 


0 - keystroke valued 71 by [WKEY 

1 - tried to leave a field not containing a valid 
number 

2 - keystroke would have exceeded field's data 
capacity 

3 - keystroke not acceptable in the field 

4 - user pressed a key to move to the next field 
and the exit-for-validation flag was set for 
this field 

5 - timeout. 
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Note that exit types 1, 2, 3, and 4 can only occur 
if column 6 of the right argument calls for 
Checking them; otherwise validation is ignored and 
overflow and invalid characters just beep. If 
more than one exit condition is met, the higher 
number is returned. 


[2] the keystroke that caused the exit from [WIN (in 
numeric DINKEY value) 


[3] which field vas active (row index in right 
argument) (zero origin) 


[4] row in active field of cursor at exit (zero 
origin) 


[5] column in active field of cursor at exit (zero 
origin) 


The remaining elements are Boolean indicators of 
whether anything vas ever changed (1) or not (0) in 
each field described by the right argument. 


Effect 


Executing "WIN allows the user to perform full-screen 
entry, within the specified windows and the limits of which 
keystrokes are permitted in each field, until he uses a 
keystroke that exits from (WIN: a keystroke assigned a ^1 
code by (WKEY (defaults are Escape and Ctrl Enter) or one of 
the special feature events selected by column 6 of the right 
argument. 


During the execution of (WIN, the regular cursor is 
used for replacement input, while the terminal mode cursor 
is used for insertion input. 


The final form of the screen contents is left on the 
Screen while the explicit result reports on the exit method, 
exit position, and which fields have had characters typed 
into them. 


BREAK and Exit also exit from (WIN, unless disabled or 
weakened by a DPOKE. The default (unpoked) behavior of Exit 
Clears the state indicator and returns no explicit result, 
while BREAK returns an explicit result whose first element 
is 0, and executes a weak interrupt at the end of the 
Statement containing (WIN. BREAK and Exit take priority 
Over refusing to leave a field unless a number is valid. 
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Examples 


The workspace INPUT, distributed with the APL*PLUS/PC 
System, contains several working examples using (WIN. 


(WIN 20 2015 10 1 122 (Sets up a limited window 


for unlimited character 

input on the screen, using 
one display attribute for 
the field while in it, and 
another upon leaving it.) 


DIN 2 8p00 18 71 0 112 7 10 10 3 10 2 1 112 7 


(Sets up two input fields, 
the first taking any kind of 
input characters, the second 
accepting only numeric.) 


WHOLE [WPUT MENUTEXT (Put up the text of a menu.) 
DEIN WINDOWSANDATTRIBUTES (Use attributes to highlight 


Error Reports 
DOMAIN ERROR 


LENGTH ERROR 


RANK ERROR 


WS FULL 


the menu with all fields of 
type 0: exit with Esc, 
getting choice from explicit 
result.) 


An argument is not integer or contains a 
value greater than 32767 or a negative 
value other than as the fourth element of 
the left argument. Or, the left argument 
specifies a non-existent initial field, or 
a cursor location not within the initial 
field. Or, the right argument contains an 
invalid window specification. 


The left argument has more than four 
elements. Or, the right argument has too 
few columns for a complete window 
specification, 


The left argument is not a singleton or a 
vector, or the right argument is not a 
vector or matrix. 


The explicit result requires more 
workspace storage than is available. 


Copyright 1983 STSC, Inc.  3-288.6 System Functions 


OWINDOW -- Window Specification DWINDOW 


The session-related system variable [WINDOW contains 
the specification of the window on the screen vithin which 
all system displays and reads are done. Its value is a 
vector containing the first row and first column of the 
window followed by the window size (number of rows and of 
Columns). (WINDOW, as described here, is specific to the 
APL*PLUS/PC System; it may be different or absent in other 
APL*PLUS Systems. 


Domain 


The domain for assignment to (WINDOW is a non-negative 
integer vector whose first and third values totaled cannot 
exceed the number of lines on the screen, (CRT (LIO + 4), 
and vhose second and fourth values totaled cannot exceed the 
number of columns on the screen ({)CRT [DI0*5]). 


Value when Referenced 


When WINDOW is referenced, its value is a vector of 
four integers within the domain. The first two elements are 
the absolute screen position of the upper-left corner of the 
window, and the last two elements are the shape of the 
vindow. 


Default Value at Session Start 

At the start of an APL session, the default value for 
WINDOW is © 0 25 80 (or © © 25 40 for 40-character 
Screens). Some branós of personal computer may have a 
different maximum number of lines on the screen. 


DWINDOW-Dependent Primitive and System Function: 


The value of (WINDOW is used in connection with 
LCURSOR, which is relative to the upper-left corner of the 
current window, to determine the absolute screen location. 


Effect 


When normal screen input or output is done, it is 
limited to the rectangle on the screen described by [WINDOW. 
The first two elements of the current value are taken as the 
row and column numbers of the upper-left corner of the 
window (in origin 0). The last two elements are taken as 
the window size, the number of rows and of columns contained 
within the window. 


If the current cursor position lies outside the new 
window, it is moved to the upper-left corner of the window. 
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1f a function shifts the display in use from 80-column 
to 40-column and adjusts only the localized value of 
DWINDOW, then upon return from the function, the global 
value could prove to be larger than the display in use. 
QWINDOW then automatically takes on the full size of the 
e@ isplay in use. Exit also resets the window to full screen. 


Examples 
OWINDOW 
0 0 25 80 (The default value or 
full screen.) 
DWINDOW + 0 O 10 80 (Use only the top ten 


lines of the screen, 
protecting the data below 
that from scrolling or 
clearing by DTCFP.) 


“WINDOW + 10 0 15 80 © [I]TCFF (Clear the screen below 
the top lines.) 


DWINDOW + 0 40 25 40 (Preserve the data of the 
left half of the screen. 
Work on the entire right 


half.) 
Error Reports 
o DOMAIN ERROR The value being assigned to (WINDOW 

describes a window that does not lie 
entirely on the screen. Or, the value is 
non-integral, containing characters or 
fractional numbers. Or, it specifies a 
window with no rows or ne columns. 

LENGTH ERROR The value being assigned to WINDOW is a 
vector but does not have four elements. 

RANK ERROR The value being assigned to DWINDOW is a 
scalar, or a matrix or higher-dimensional 
array. 
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OwxeY 


The ambivalent system function WKEY reports on or 
changes the defined behavior of keystrokes entered during 
the execution of [WIN on a key-by-key basis. This in turn 
allows user definition of field types usable within [DWIN. 
DWKEY is experimental in this release of the APL*PLUS/PC 
System; it may be different, absent. or replaced by an 
entirely different feature in a subsequent release. 


Syntax 


result + O’WKEY keystrokes 
result + newdefs WKEY keystrokes 


result - the explicit result, existing behavior 
newdefs - an integer singleton or vector of new 


behavioral codes 
keystrokes - a singleton or vector of specified 
keystrokes, either character or numeric 


Arguments 


The optional left argument to lWKEY is an integer 
Singleton or vector of behavioral codes to be used in 
subsequent executions of [WIN for the corresponding 
keystrokes in the right argument. A singleton left argument 
extends to any number of keystrokes in the right argument. 


The right argument to [WKEY is a singleton or vector of 
keystrokes whose behavior during (WIN is to be reported or 
altered. The keystrokes can be represented as characters 
for values that occur in [MY, or as integers ranging from 0 
to 511 inclusive, matching the keystrokes corresponding to 
the values returned as numeric results of CINKEY. 


The behavioral codes that [WKEY associates with each 
keystroke are integers ranging from 32768 to 32767 
inclusive. 


A positive behavioral code assigned to a keystroke 
represents the list of field types vhere the keystroke is 
acceptable. The list is represented as a sum of field 
identifiers. The field types are identified by powers of 2 
(1, 2, 5, B, ... , 16384). Each field type is thus defined 
as a field permitting those keystrokes whose associated 
behavioral codes are positive integers that include the 
field's identifier in its composite sum. For example, to 
make "A" an acceptable keystroke in field types 1, 2, and 8 
(where i and 2 are system-defined field types, and 8 is 
user-defined): 


(1*2+8) DWKEY ‘a’ 
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The behavioral code 0, therefore, means that the keystroke 
is unacceptable everywhere, and will produce a beep if 
pressed. The field type 0 is a restricted field (no data 
entry keystrokes accepted), but the cursor can pass into and 
out of such a field, rather than skip over it. While the 
cursor is in a restricted field, that field (and its active 
attribute if any appears) is active, providing a simple 
means of making a menu. 


A negative behavioral code represents a 
re-interpretation of the corresponding keystroke according 
to the following table: 


Value Action By default, on key 
exit from [WIN Escape and Ctrl 
Enter 
c2 to next field Tab 
73 back to previous field Backtab (Ctrl Tab) 
la to first field Ctrl Home 
E to last field Ctrl End 
6 to first column of next Enter 


line; or, from bottom of 
field, to next field 

7 untype (delete character and Untype 
close up) 

8 delete (and close up without Delete 
Cursor movement) 


Switch between insert and Insert key 
replace modes (like Alt 
= Overstrike) 
10 cursor up, or, from top of Up 


M field, to higher field 
11 cursor down, or, from bottom Down 
of field, to lower field 
12 cursor left, or, from left Left 
edge, to previous field 
13 cursor right, or, from right Right 
edge, to next field 


Tin to left edge of field Home 
ES just past last character in Ená 

E field 

16 cursor up four lines, even Ctrl Up 


E past field boundaries 
17 cursor down four lines, even Ctrl Down 
past field boundaries 


718 cursor left eight columns, Ctrl Left 
" even past field boundaries 
19 cursor right eight columns, Ctrl Right 


even past field boundaries 
.30 erase to right edge of field Alt + 
231 erase to left edge of field Alt + 
32 erase to end of field Alt End 


The values 20 through ^29 perform the same actions as 
the values 10 through 19 respectively, but do not leave 
the field. They are not found on any default keys, but are 
available for use providing special controls in (win. 
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Values of ^33 or less are ignored. 

NOTE: Since [WKEY is experimental in this release, defaults 
may change. We recommend that you set all 512 values 
with DWKEY. 

Effect 

The effect of a monadic use of [WKEY is to report the 
current behavioral codes for the keystrokes in the right 
argunent. 

The effect of a dyadic use of [WKEY is to alter the 
current behavioral codes for the keystrokes given in the 
right argument to those given in the left argument. 


You can record the current value of [WKEY for later 
restoration by using monadic [WKEY: 


ORIGKEYS + LWKEY(1512)-[]I0 


Alternatively, the following function can be used to restore 
default values: 


9 DEFAULTWKEYS;DIO 


[1] II0-0 o i (WEY 1256 © 3 ÜWKEY '0123556789.E,- ' 

[2] 255 [WKEY 256*1256 

[3] 0I0-1 o (-19) IWKEY 438 424 425 367 370 13 437 432 4323 

[a] (9-110) CWKEY 393 520 391 389 394 388 259 261 258 257 
7 

esult 


The explicit result of [WKEY is an integer vector 
containing one behavioral code for each keystroke in the 
right argument. Monadic [WKEY returns the current behavior 
for the keys; dyadic OWKEY returns the behavior of the keys 
before they were replaced. 


Examples 
(14248) [WKEY '4* (Sets "A" to type 11, able to 
appear in fields of types i, 2. 
or 8.) 
T1 DTWKEY 424 (Tab key exits from [WIN.) 


T3 T4 "WKEY 394 393 392 
(Makes Home, Up. and PgUp keys 
act respectively as move to 
next field, move back to 
previous field, and move to the 
first field.) 
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NEVBATCE [WKEY (1512)-0IO 
(Reassigns all keystrokes if 
NEWBATCH is a 512-element 
vector, ) 


71 QREY (1512)-CI0 (Anything not otherwise e 
Specified exits from [WIN.) 


3 CWKEY '0123456789' (Any digit can occur only in 
fields of type 1 or 2.) 


Error Reports 


DOMAIN ERROR The right argument contains numeric values 
that are not integers between 0 and 511 
inclusive. Or, the left argument contains 
Characters. Or, the left argument contains 
values that are not integers between 32768 
and 32767 inclusive. 


LENGTE ERROR The left argument is not a singleton and has 
a length different from that of the right 
argument. 


RANK ERROR An argument is neither a singleton nor a 
vector. 
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Wry? -- Put Window Data WENT 


The ambivalent system function [WPUT replaces the 
characters or attributes or both in a specified (or in the 
current) screen window. ‘WPUT, as described here, is 
specific to the APL«PLUS/PC System; it may be different or 
absent in other APL*PLUS Systems. 


Syntax 


WPUT data 
wspec -WPUT data 


wspec - optional specification of a window other than 
the current one 

Sata - the data to replace the current data in the 
window 


Arguments 


The optional left argument is a specification of a 
window to be used during this one operation, and has the 
same effect as setting -WINDOW before the operation and 
resetting it after the operation. If there is no left 
argument, the current window is used. 


The right argument to (WPUT is the data to replace the 
current contents of the vindow. The data array can be any 
of the four array results of the WCET function. If the 
Shape of data does not match the window size and its rank is 
less than 3, it will be reshaped to fit the specified 
vindow. 


Result 


:WPUT returns no explicit result. 
Effect 


The function WPT replaces the displayed characters 
(if data is a character array with rank less than 3), the 
attributes (if data is integer with no values outside the 
range 0 to 255 inclusive), or both (if data is integer with 
any values outside the range 0 to 255 inclusive or is a rank 
three character array). 


The attribute values used with (WPUT are, by default, 
interpreted as IBM-specific, but can be set to 
interpretation as generic attribute values by -POKE. 


Generic Attribute Values 


© = normal (white on black) 
H inverse video 

2 - high intensity 

4 = blinking 

8 = underscored 
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Any combination of the non-zero attributes can be 
represented by using the sum of the values for those 
attributes when generic attributes are in effect. Functions 
using these values can run unaltered on varied hardware 
where the native attribute values are different. 


NOTE 


if the CPOKE is changed during an APL session, 
attributes read from the screen earlier in the 
session with [WCET may change if they are later 
restored with [WPUT. In addition, imperfect mapping 
between generic and IBM-specific values may cause 
different attribute values to occur. 


When the generic attributes are not in use, the 


following IBM-specific values prevail: 


240 
248 


they 


non-display 

underline 

white character/black background 

underline, high intensity 

white character/black background, high intensity 
reverse video 

reverse video, high intensity 

underline, blinking 

white character/black background, blinking 
underline, high intensity, blinking 

white char/black background, high intensity, blinking 
reverse video, blinking 

reverse video, high intensity, blinking 


Other values are possible, but on a monochrome display 
merely duplicate these effects (see your computer 


manufacturer’s manual for more information). 


Attribute Values for Character Color Screen 


attribute = foregroundcolor 
backgroundcolor ) 
intense ) 

128 x blinking ) 


+++ 


or, 
attribute = 2 8 2 8 4 blink, background, 
intense, foreground 


colors: 0 


NOD EWN 


Copyright 1983 STSC, Inc. 3-292 System Functions 


Notes: White background vith black foreground is reverse 


video. 


Black on black is invisible (like monochrome 
non-display). 


Grey is low-intensity white. 


White on white gives white on black. e 


Brown is low-intensity yellow, 


Examples 
ZWPUT W1 (Place the character matrix of 
data Wi in the current 
window.) 
0 0 1 80 DWPUT 112 (Cause the first line of the 


Error Reports 
DOMAIN ERROR 


LENGTH ERROR 


RANK ERROR 
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screen to display in reverse 
video.) 


The left argument is not in the domain 
of CWINDOW, the right argument contains 
floating-point values or integers not in 
the range from 732,768 to 65,535 
inclusive. Or, the right argument has 
rank 3, but is not character valued. 


The left argument is a vector whose 
length is not *; the right argument is 

rank 3, but its last dimension is not 2 

or its first tvo dimensions do not match 

the shape of the current or specified 

window, 


The left argument is not a vector; the 
right argument is of rank greater than 
3. 
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WSID -- Workspace Identification DwsID 


The niladic system function [WSID returns the 
identification of the active workspace. 


Syntax 
result + DWSID 
result - the explicit result 
Result 
In a named workspace, the explicit result of [WSID is a 


22-element character vector containing the workspace 
identification in the folloving format: 


Columns 1-10 Library number, right-justified 
Colum 11 Blank 
Columns 12-22 Workspace name, left-justified 


In a clear vorkspace, the result is an empty vector. 


If you have programs that were written using an earlier 
version of the APL»PLUS/PC System (when the explicit result 
of CWSID was 10-columns wide), these programs can be used 
without modification after using []POKE to adjust the output 
format of [WSID, DFLIB, and [WSLIB. 


Example 
WSID 

IS 1 ANSWER 
WSID 


1 ANSWER 
eWSID 


Error Report 


WS FULL The explicit result requires more 
workspace storage than is evailable. 
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[ESLIB -- Workspace Library List UWSLIB 


The monadic system function [WSLIB returns a character 
matrix listing all the vorkspaces in the designated library. 


Syntax 


re 


lt + DWSLIB lib 


result - the explicit result 
lib  - an integer designating a library 


Argument 

The argument designates the library whose workspaces 
are to be listed. It must be a non-negative integer, or an 
empty vector (which indicates all active libraries at once). 


Result 


The explicit result of fWSLIB is a 22-column character 
matrix containing one workspace identification per row. The 
ordering of the rows is alphabetic. The columns in the 
result are defined as follows: 


Columns 1-10 Library number 
Column 11 Space 
Columns 12-22 Workspace name, left-justified 


1f you have programs that were written using an earlier 
version of the APL«PLUS/PC System (when the explicit result 
of OWSID was 10-columns wide), these programs can be used 
without modification after using (POKE to adjust the output 
format of (WSLIB, [WSID, and .'FLIB. 


AUTION: The number of columns in the result of (WSLIB 
may increase in the future. 


NOTE: WSLIB produces the same list of workspaces, but 
listed in multiple columns to save lines on the screen. 


Examples 
DKSLIB 1 
1 FINANCE 
1 GAMES 
WSLIB 0 


0 FILEAID 
Q FORMAT 
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DWSLIB '* 
O FILEAID 
O FORMAT 
1 FINANCE 
1 GAMES 


pOŪWSLIB 8 
4 22 


Error Reports 
DISK ERROR 


DOMAIN ERROR 


RANK ERROR 


WS FULL 


A disk error has occurred, probably due to 
a hardware fault or to an unformatted or 
defective disk. 


The argument is negative or is not 
integer-valued. 


The argument is not a singleton or an 
empty vector. 


The explicit result requires more 
workspace storage than is available. 
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(WSOWNER -- Workspace Owner OWSOWNER 
The niladic system function [WSOWNER returns the user 


number of the owner of the saved workspace on which the 
active workspace is based. 


tas © 
result ~ [WSOWNER 
result - the explicit result 
Result 
The explicit result of DWSOWMER is a numeric scalar 


containing the user number of the user vho saved the 
workspace. In a clear workspace, the result is 0. 


Example 
DWSOWNER 
32107 
Error Report 
WS FULL The explicit result requires more 
workspace storage than is 
available. 
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DWSSI2E -- Workspace Size OWSSIZE 


The niladic system function [WSSIZE returns the number 
of bytes in a clear workspace with the current software and 
hardware configuration. 


Syntax 
result + [WSSIZE 
result - the explicit result 


Result 


The explicit result of [WSSIZE is a numeric scalar 
containing the number of bytes of usable space (DWA) plus 
the symbol table in a clear workspace with the current 
software and hardware configuration. In the APL*PLUS/PC 
System, it will vary with the amount of memory in your 
personal computer and whether space has been reserved for 
non-APL usage under DOS. 


Example 
IWSSTZE 
102483 
Wa 
26782 
DWSSIZE - [WA 
67701 (The approximate number of bytes 
needed to store this workspace on 
disk.) 
Error Report 
VS FULL The explicit result requires more 


workspace storage than is available. 
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DESTS -- Workspace Timestamp Owsrs 


The niladic system function [WSTS returns the time of 
the most recent )SAVE or )CLEAR performed on the active 
workspace. 

Syntax 


result + -WSTS 
result - the explicit result 


Result 


The explicit result of [WSTS is a numeric scalar 
containing the time of the most recent )$4VE or )CLEAR 
performed on the active workspace. The value is expressed 
in microseconds since 00:00 on 1 January 1900 for 
consistency with other APL*PLUS Systems. The personal 
computer's system clock, however, determines the useful 
precision of any time measurements: the values are drawn 
from the system clock maintained by DOS, which reports them 
in centiseconds. 


Example 
LOAD MYWS 

O MYNS SAVED 2/15/1983 11:55:18 
WSTS 


2.623060518E15 

)COPY 1 FILEAID TIME 
1 FILEAID SAVED 

TIME WSTS 
2/14/1983 11:55:18.000000 


Error Report 


WS FULL The explicit result requires more 
workspace storage than is available. 
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LOAD -- Load a Workspace, Suppressing Execution QxLoaD 
of [zy 


The monadic system function [LOAD replaces the active 
workspace with a designated workspace without executing the 
latent expression (DLX) that is stored in it. 


Syntax 
DXL04D wsid 


wsid - a character vector or singleton containing the 
workspace identification 


Argument 


The argument to LXLO4D is a character vector or 
singleton containing the identification (optional library 
number and name) of the saved workspace to be loaded. 


The workspace can be in any active library. 1f no 
library is specified, the current default library is 
assumed. 


Result 
The function DXLO4D does not return an explicit result. 
Effect 


When LILOAD is successful, the contents of the active 
workspsce are replaced by the contents of the designated 
library workspace, and the SAVED message is displayed. 


DXZ04D allows a user to suppress execution of the 
latent expression LLX. The user can thereby examine the 
workspace and its latent expression in the exact form in 
which they are saved. 


xam 


QXLOAD 'STARTUP' 
O STARTUP SAVED . . . 
On 
2+3 
A NOTE THAT THE OLY DID NOT EXECUTE. 
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Error Reports 
DISK ERROR 


DOMAIN ERROR 


DRIVE NOT READY 


INSUFFICIENT HANDLES 


INVALID WS NAME 


LIBRARY NOT FOUND 


NOT YOUR WS 


RANK ERROR 
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A disk error has occurred, probably 
due to a hardware fault or to an 
unformatted or defective disk. 


The argument has the proper rank 
but is not character-valued. 


An attempt has been made to use an 
empty or non-existent disk drive. 


The maximum number of files that 
DOS allows open at one time would 
be exceeded. If you can untie a 
file, you can free a handle for the 
attempted operation. To increase 
the number of handles available, 
include FILES=n (where n is 5 more 
than the desired file tie quota) in 
your CONFIG.SYS file and reboot the 
System. For the default file tie 
quota of 10, use FILES-15. 


The specified workspace 
identification is ill-formed. 


The APL library (DOS directory) you 
are trying to use cannot be found 
on the disk in the disk drive 
indicated by LL18$. Failure to 
find the library may result from 
not including a space between the 
library number and workspace name. 


The specified workspace was not 
saved by the account number 
currently in use. 


The argument is not a vector or 
singleton. 
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WS NOT COMPATIBLE 


WS NOT FOUND 


WS TOO BIG 
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The specified workspace was saved 
with suspensions under an earlier 
version of the system, from a 
machine with a different amount of 
memory, or at a time when the 
absolute loading address of the APL 
system was different (for example. 
under a different version of DOS 
It cannot be loaded under this 
version until )LO4D, }SIC, and 
)SAVE have been executed on the 
workspace under that version of the 
system, All user-defined functions 
and variables can be copied (using 
)COPY) from the local environment, 
however. 


The designated workspace does not 
exist in the specified or default 
library. 


The specified workspace is too 


large to load in the amount of 
memory available in this machine. 
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@ GLOSSARY 


abort 


Interrupt and abandon execution of a program or a 
session that is in progress. 


access matrix 


A matrix associated with each APL component file in the 
APL*PLUS/PC System. The matrix consists of three 
columns containing: the user account numbers of those 
who have been given access permission of some sort; the 
sums of the access codes granted to each user; and the 
access passnumbers (if any) required of each user. 


account number 


A number (ranging from 0 to 32,767) that identifies a 
user account. The user provides this number to the 
system at the beginning of an APL session. The user 

@ account number is the value of Ü4I[1]. User account 
numbers appear in the first column of file access 
matrices, 


accounting information 


Information consisting of the user account number, the 
elapsed time in seconds since the start of the APL 
session, and the number of characters typed by the user 
and the system respectively. This information is 
returned by the system function JAI. 


active workspace 


The workspace that is currently in the computer's CPU 
memory. The last workspace loaded by the user. If the 
user has just begun an APL session, the active 
workspace is either CLEAR WS, the start-up workspace 
for the user account number in use (if found), or a 
workspace loaded by W=. The name of the start-up 
workspace for user account number 213, for example, 
would be INI213. 


[] address 
An identification that designates a particular location 
in the computer's memory. 
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algorithm 


A set of well-defined rules for solving a problem in a 
finite number of steps. 


Alt key [ ] 
One kind of shift key for which a red key label has 
been provided. 


ambivalent function 


A function that requires a right argument, but for 
which having a left argument is optional. 


APL file 


A collection of sequentially numbered APL arrays 
(called components) that are stored on disk. APL files 
are created and manipulated by system functions whose 
names begin with "CIF". 


application program 


A program that enables the computer to perform a 
specific job, often written in a high-level language 
such as APL, possibly with some parts written in 
assembly language. 


The data on which a function acts. 
array 


An arrangement of elements into zero, one, or more 
coordinates (dimensions). All elements of any given 
array in the APL*PLUS/PC System are of the same 
datatype. 


array shape 
See "shape of an array". 
ASCII 


Acronym for American Standard Code for Information 
Interchange. The standard code for information 
interchange among data processing systems, 
communication systems, and associated equipment. Uses 
a coded character set consisting of seven-bit coded 
characters (with an eighth bit available for parity 


checking). e 
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Assembly language 
À low-level symbolic programming language, closely 
resembling machine-code language, that allows a 
Computer user to write a program using mnemonics 
instead of numeric instructions. 

atomic vector 
The vector that contains all of the possible character 
values in an APL system. These character values can be 
referenced using the system function DAV. 

attention 


An interrupt issued by pressing BREAK while an APL 
Statement or function is executing. 


autorepeat 


The feature that allows you to hold a key. producing 
the same result as pressing the key multiple times. 


AXIS ERROR 
An error occurring from an attempt to select a 
non-existent or invalid axis (coordinate) of an array 
for use vith a function or operator. 

backspace character 
A non-graphic character which causes the cursor to move 
one position to the left. Available in APL»PLUS 
Systems as DTCBS. 

backup 
An extra copy of stored data which can be used in case 
of accidental damage to or inadvertent erasure of the 
original (caused either by human error or machine 
failure). 

baud rate 


The speed of transmitting data to peripherals or other 
computers. See also "BPS". 


bell character 
A non-graphic character which produces a bell sound on 


many ASCII devices. Available in APL«PLUS Systems as 
LITCBEL. Sounds a tone on the APL*PLUS/PC System. 
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binary 


A number representation system with a radix of 2; 
numbers are written using only the digits 0 and 1, 
where each additional place to the left represents an 
increasing power of 2. just as in normal decimal 
numbers each place represents an increasing power of 


10. 

bit 
Shortened form of binary digit. The smallest unit of 
data on computers. A single character in a binary 
number; that is, 0 or 1. 

Boolean 
Numbers with values of either 0 or 1. 

boot 
See "bootstrap". 

bootstrap 
A procedure for starting the loading of a program 
(usually the operating System) into a computer as a 
result of preliminary instructions. This procedure is 
initiated by a switch or by a keyboard input command. 
Also called "IPL". 

BPS 


Abbreviation for bits per second. A measure of data 
transmission speed showing the number of bits of 
information that pass a given point in one second. 
Bytes per second in ASCII transmissions is usually 
approximately BPS divided by 10. 


branch potential 
The indication of whether an APL statement terminated 
with a successful branch. One of three potentials 
associated with an APL statement after it has executed, 
Contrast with "display potential", "value potential”. 

branch statement 
A statement in a defined function which changes the 
order of execution of statements in that function. See 
"conditional branch", "unconditional branch". 

branch target value 


The line number to which a branch is to be made. 
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BREAK 


A signal sent from the keyboard to indicate that 
current processing should be interrupted, or that the 
line being entered should be abandoned; signaled in the 
APL*PLUS/PC System as Ctrl Break (holding the Blue key 
while pressing the Break key). 


BREAK signal 
The result of pressing BREAK. 
buffer 


A fixed-size internal storage area that is dedicated by 
the system to a particular purpose. such as holding 
data received from a port until it is used. 


byte 


A sequence of adjacent bits used as a unit of data. 
One byte usually contains 8 bits, as in the APL*PLUS/PC 
Systen. 


calling environment 


The environment from vhich a function is called upon to 
execute and to which the computer returns after its 
execution, possibly with the explicit result to be used 
at the point where the function was called. With 
respect to the execute primitive function (e) the way 
in which execute is invoked; in particular, whether or 
not it appears as the leftmost function in the 
statement. If it does, then it is not expected to 
return a value. If it does not, then it must return a 
value (otherwise a VALUE ERROR is reported). 


canonical representation 
The representation of a given function which is formed 
by converting the function into a character matrix in 
which each row is a line of that function. The 
explicit result of OCR. 


caret 


In an error display, a pointer where the problem vas 
encountered. Represented by the caret symbol (4). 


catenate 


To join two arrays to form a single larger array. 


Character 


Any symbol, letter, digit, or punctuation mark used to 
control or represent data. 
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Character constant 


A series of characters enclosed between single quotes. 


character data 


Data, consisting of symbols (visible or not) used by 
the keyboard, screen, communications, or printing 
devices. Each symbol occupies one byte of storage and 
found among the 256 unique elements of the atomic 
vector (JAV). One of two datatypes in APL. Contrast 
with "numeric data". 


character input mode 


The input mode invoked when | executes. The system 
provides no distinguishing prompt for the user entry. 
The result is a character vector of the user entry 
(possibly preceded by a program-issued prompt) with no 
execution or command processing of the user entry. 
Character input mode is normally ended by pressing 
Enter, but can be aborted by using Exit or with input 
of 0, Over, V, Over, T. Contrast with "evaluated input 
mode". 


chip 


A single hardware device consisting of transistors, 
diodes, and other components forming the essential 
elements of an electronic circuit. Many chips are 
manufactured at the same time as small sections of a 
wafer sliced from a crystal of silicon. Each chip is 
usually encased in a rectangular plastic or ceramic 
package with two parallel rows of pins that connect it 
to a circuit board. 


clear vorkspace 


An active workspace created by the )CLEAR command. It 
has no workspace name, contains no user-defined 
functions or variables: all workspace-related system 
variables have their default values. 


clock 


A device capable of generating signals at periodic 
intervals. 


command 


A word related to a particular computer operation that 
can be used alone or with additional information to 
cause that operation to be performed. Most commonly 
used for the operating system or for APL system 
commands. 
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compaction 


Reclaiming disk storage space abandoned in a component 
file by replacing file components with components of a 
different size. 


comparison tolerance 
The limit within which two APL values being compared 
are judged to be close enough to each other to be 
considered equal. The amount is controlled by the user 
through DCT. Also referred to as "fuzz". 

component 
See "file component", 

component fiie 
See "APL file". 


compound statement 


Two or more statements vritten on a single line and 
separated from one another by diamond symbols (9). 
Compound statements are executed from leftmost in 
order, to rightmost. 


computer program 


A set of instructions (called "statements" in APL) 
expressed in a form suitable for execution by a 
computer. Also called a "program". 


conditional branch 


A branch statement whose effect is dependent on some 
specified condition, The argument to a conditional 
branch may evaluate to a numeric array whose first 
element is used as the destination or to an empty 
array, resulting in no branching being done. Contrast 
with "unconditional branch". 


conformability 


The required rank and shape relationship of array 
arguments of a function, 


constant 


An array whose content is specified at the point of 
call (where it is to be used), rather than referring to 
another source for the data (such as a variable). See 
"character constant", "numeric constant", "variable". 
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control character 


A character produced by pressing a key while holding 
down the Ctrl key. 


control key 


The key labeled "Ctrl" and its functional duplicate on 
the cursor pad. 


conversion type 


Specifications for interpreting and storing the data 
bits read from a native file. 


coordinate 


An axis along which data is arranged in an array, 
allowing indexing (subscripting) selection. To select 
a single element of data, a single index must be 
specified for each coordinate. The lengths of all 
coordinates of an array are given in the array's shape 
vector. 


CPU 


Acronym for Central Processing Unit. The part of a 
computer that controls the interpretation and execution 
of instructions. 


crash 


Also called a system crash, is a failure of either the 
hardware or of the software. A crash leaves the system 
in an unusable state; the system must be restarted 
either by re-booting or by powering off and then on 
again. (A pause of about five seconds may be needed 
before turning the personal computer back on.) 


CRT 


Acronym for cathode-ray tube. A television-like device 
used for displaying text and possibly graphic images. 


Ctrl 


One kind of shift key (also called control) for which a 
blue keyboard label has been provided. A notation for 
control code entries from the terminal keyboard. For 
example. Ctrl S means that the user presses the S key 
while holding down the Ctrl key. 


cursor 
Position where the next input or ovtput character will 


appear on the screen. Indicated during input by a 
blinking underline on the screen. 
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data 


A collection of numbers or characters. Datatypes in 
the APL*PLUS/PC System are classified as numeric or 
character. See "character data", "numeric data". 


decimal 


The number representation system using the base (radix) 
10. Compare "binary", "hexadecimal notation". Also, a 
synonym for decimal point. 


decoration 


An optional modifier used as part of the left argument 
to the APL*PLUS System function “FMT. Displays the 
specified text with numeric data. 


default 


A value used by a system or language translator when no 
other value has been specified by the user or his 
program. 


default disk drive 


The disk drive that DOS uses when no disk drive has 
been specified. The letter representing this disk 
drive, followed by a separator character, is used as a 
prompt in DOS. 


default library 


The library used when no library number has been 
provided, 


default value 


A predetermined value used when no explicit choice is 
made or when no explicit action is taken to set the 
value. 


defined function 


An APL program defined by the user while in definition 
mode or by using GDEF, (DEFL, OFX, or the full-screen 
editor, A defined function consists of a header line 
(that formally specifies the function name, any 
arguments, and any result) and lines of APL statements. 
One of three function types in APL, Also called 
"user-defined function". Contrast with “primitive 
function", "system function". See also "function". 


defined name 
An APL identifier currently being used as the name of a 


function, variable, or label in the workspace. A name 
that does not produce a VALUE ERROR when referenced. 
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definition mode 
See "function definition mode". 
DEFN ERROR (definition error) 


An error occurring when the system is unable to alter a e 
defined function in the way requested. 


detached 1/0 


The use of APL files as replacement input sources or 
output or capture sinks, by using ICAP, DIN, or DOUT. 


diamond symbol 


The symbol (9) used to separate the individual 
statements in a compound statement. 


digit 
A graphic character that represents an integer; one of 


the characters 0 through 9. Also called "numeric 
character". 


dimension 


The number of elements along a single coordinate of an 
array. The maximum size of the number and arrangement 
of elements in an array. Also called "coordinate". 
See also "shape of an array". 


directory 


System table space used to control data storage and 
retrieval in a file. A table of identifiers and 
references to the corresponding items of data. Also, 
DOS's table of information on a group of files 
(possibly the entire contents of a disk). 


disk 
A non-volatile, rotating, data storage device whose 
circular surface is coated with magnetic material. The 
most common disks used with personal computers are 
5.25-inch "floppy" disks and "hard" (Winchester) disks. 


disk drive 


A hardware device that rotates a disk, permitting 
electromagnetic reading and writing of data. 


diskette o 


Synonym for a disk (mini-disk). See "disk", 
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display 
A visual presentation of data. 

display potential 
The indication of whether the value of an APL statement 
is to be displayed. If the statement has no value, 
display potential is undefined. One of the three 
potentials associated with an APL statement after it 
has executed. Compare "branch potential", "value 
potential". 

domain 


The set of arguments (or of pairs of arguments) for 
which a fonction is defined. 


DOMAIN ERROR 


An error occurring when a function is executed vith one 
or more arguments not in its domain. 


dyadic function 


A function that requires both a left and a right 


argument. 

edit 
To add to, change, or delete from an existing program 
or set of data. 

elements 


The individual items in an array. In an array of 

Character data, each character is an element; in an 

array of numeric data, each number is an element. 
empty array 


An array having one or more dimensions of length zero. 
The number of elements in an empty array is zero. 


empty vector 
An empty array of one dimension (6 or ''). 


Enter 


The key that you press to indicate that you have 
finished typing a line of input and that the line 
should now be processed. Called "Return" on some 
computer manufacturers' keyboards. 
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error 


A statement or command that cannot be executed, usually 
done to incorrect construction, unacceptable values, or 
hardware constraints or failures. 


error handling 


The use (via DELI) of preplanned responses to errors 
encountered in statement execution. 


error message 
See "error report". 
error report 


A message produced by the APL*PLUS/PC System when it 
encounters a statement or system command it cannot 
execute. 


escape character 


A non-printing character, typically with transmission 
code 27, accepted by some communicating devices as a 
Signal that subsequent characters are commands to alter 
option settings in the device. 


evaluate 
To calculate. See also "execute". 
evaluated input mode 


The input mode when D executes. The system prompt in 
this mode is ^. User entry is evaluated as an APL 
statement whose last explicit result is the value used 
as input. Evaluated input mode is normally ended by 
typing Enter. Evaluated input mode can be aborted by 
typing Exit or by entering a branch arrow (+) without 
an argument. Contrast with "character input mode". 


execute 


In computer programming, to interpret a computer 
instruction and carry out the operations specified by 
the instruction, Also called "run". Also, an APL 
function, denoted by the symbol s, which takes a 
character vector or scalar as its argument and 
evaluates (executes) the APL statement represented in 
the argument. See also "evaluate". 


execution mode 


Synonym for "immediate execution mode". 
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explicit coordinate 


A coordinate to a primitive function that is specified 
by enclosing it in brackets. For instance, in +\[2]4, 
the explicit coordinate is 2. Contrast with "implicit 
coordinate". 


explicit result 


A value produced as a result of expression evaluation 
that is available for use in subsequent expressions. 


expression 


Identifiers, constants, and/or primitive functions and 
operators in syntactic combination. See also "latent 
expression". 


extension 
See "file extension". 
file 


A linear collection of related data records arranged on 
disk in a prescribed sequence. The user can 
communicate information to, and access information from 
a file using the APL*PLUS/PC System's file system 
functions. In an APL file, a linear collection of 
arrays (called components); in a native file, a linear 
collection of characters (called bytes). See also 
"native file". 


file component 
The fundamental storage reference point in an 
APL*PLUS/PC System shared component file. Any APL 
&rray can be stored in a file component. 

file extension 


The period, and zero to three alphanumeric characters 
following the name of a DOS file. 


file identification 


The combination of library number and file name (or, in 
the case of native files, a library letter, colo file 
name, period and optional extension) that identifies a 
file. 


file name 
The name that identifies a file. it consists of one to 


eight alphabetic and numeric characters, beginning with 
an alphabetic character. 
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file 


file 


file 


file 


file 


file 


passnumber 

A number appearing in column 3 of a file access matrix 
that is used to control access to the file. Also 
called "passnumber". 


reservation 


The space reserved on a disk for future growth of a 
particular APL file. Also called "file size limit". 


size limit 


The size beyond which an APL file is not allowed to 
grow. Also called "file reservation". 


tie number 


A unique number used for referencing a file while it is 
in active use. 


tie quota 


The maximum number of files that can be tied 
concurrently. 


type 


See "file extension", 


floating-point 


A number able to have a fractional part. Also, the 
internal storage format used for such numbers. 


floppy disk 


A storage medium that consists of a flexible disk 
(diskette) of oxide-coated mylar stored in a paper or 
plastic envelope. The entire envelope is inserted in 
the disk drive. Also called "diskette". See also 
"disk", 


format 


The primitive function that forms numeric values into a 
character image. In the monadic form of format, the 
System chooses the width and precision of the image; in 
the dyadic form, the left argument controls the vidth 
and precision of the image. Represented by the thorn 
symbol (v). Also. to prepare a disk for accepting 
data. 
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format pair 


A pair of numbers in the left argument of dyadic thorn 
that control the format field width and display 
precision when formatting one or more columns of data 
in the right argument. 


format phrase 


A sequence of characters in the left argument to [FMT 
that specify hov a column of data is to be edited or 
positioned for display purposes. The specifications 
control the spacing, representation, precision, and 
decoration of the displayed data. 


format string 


A character vector containing one or more format 
phrases separated by commas that is used as a left 
argument to [)FMT. 


formatting 


The process of arranging data for display purposes. 
Formatting specifications control the spacing, 
representation, precision, and decoration of the 
displayed data. Also, preparing a disk to accept data, 


function 


A named procedure (program or subroutine) that 
specifies how a job is to be done. A function is 
classified as primitive (for example, +), system (for 
example, []FREAD), or defined (for example, ROWNAMES). 
See “primitive function", "defined function," and 
"system function". 


function definition 


The rule or algorithm by which a user-defined function 
is to work. A user-defined function is entered, 
edited, and displayed in function definition mode or in 
the full-screen editor. The system functions [IDEP, 
ÜDEFL, and OFX can also define functions. See 
"function definition mode”, 


function definition mode 


Entering, modifying, or displaying a "defined function" 
using the on-screen editing facilities. Compare 
"immediate execution mode". 
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function header 
The initial line of a defined function that names the 
function, models and determines its syntax, and names 
any identifiers that are local to the function. 
Referred to as line [0] when editing or using ICRI or 
JDEFL 

function line number 
See "line number". 

function type 
Defined functions can either return or not return 
explicit results. They can also be niladic, monadic, 
or dyadic. See also "dyadic function", "monadic 
function", "niladic function", 

fuzz 
See "comparison tolerance”. 

garbage 
Unwanted data remaining from a previous operation that 
has not been erased from memory. Also, any useless or 
inaccurate data. 

garbage collection 
The rearrangement of the contents of memory that 
eliminates unwanted data (garbage) to reclaim space for 
new data. 

giobal definition 


The definition of a function or variable outside of the 
current (local) state of execution. 


global environment 
The collective term for the global definitions of all 
functions, variables, and system variables in the 
active workspace. 

global variable 


With respect to a level of function execution, any 
variable not local to that function 


hardware 


The physical units making up a computer system; that 
is, the apparatus as opposed to the software or 
programs. 
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header 
See "function header". 
hexadecimal notation 


A notation of numbers using the base (radix) sixteen, 
The ten decimal digits 0 to 9 and the letters A through 
F are used to represent the digits 0 through 15, 
respectively, as single characters. One "byte" can be 
encoded using two hexadecimal symbols. Abbreviated and 
also called "hex", 


identifier 

Name of a function or variable. 
idle character 

See "null character". 


IEEE 


Acronym for the Institute of Electrical and Electronics 
Engineers. 


immediate execution mode 


The method of operation in which any entered statement 
or system command is immediately executed. Immediate 
execution mode is the initial operating mode after a 
user has begun an APL*PLUS/PC System session. Also 
referred to as "execution mode". Compare "function 
definition mode". 


implicit coordinate 
À coordinate to a primitive function that is not 
specified explicitly. For instance, in +\4, the 
implicit coordinate is the last coordinate, while in 
*XÀ, the implicit coordinate is the first coordinate. 
Compare vith "explicit coordinate". 

implicit output 
A value produced by an APL expression which is not 
re-used as an argument or assigned to a variable before 
the statement ends, and consequently is displayed. 


inclusive 


Including the numbers at each end of the range vithin 
the range. 


index 


A non-negative integer used to select an element along 
a coordinate of an array. Also called "subscript". 
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INDEX ERROR 


An error condition occurring from an index 
specification that is outside the domain of indices for 
8 given coordinate (that is, asking for an element that 
is not there). 


index origin 


The value that represents the first index position 
along a coordinate. The first number used in counting 
d the beginning. Can be either 0 or i. Represented 
by O70. 


input 
Data to be processed and instructions to control 
processing that are entered into the internal storage 
of a computer system. 

input-output 
A general term for the equipment used to communicate 
with a computer and the data involved in such 
communication, Abbreviated and also called "I/O". 


input source 


Where the input for an APL session is coming from, 
usually the keyboard, but possibly an APL component 
file selected by DIN to act as a surrogate for keyboard 
input, with each component containing one line of input 
(as built by ICAP, for example). 


integer 
A number whose fractional part is zero. In the 
APL*PLUS/PC System, an integer can range from 32,768 
to 32,767 and be stored in two bytes. Outside that 
range. integer values are stored in eight bytes. 
integrated circuit 
See "chip". 
integrity 


Protecting data from errors in normal operation, such 
as accidental erasure or entering too many digits for a 
date. 
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interpreter 


À computer program that interprets and executes each 
source language statement before interpreting and 
executing the next statement. Often contrasted with a 
"compiler", a program that translates an entire source 
language program into a machine language program 
without executing it. 


interrupt 


A signal, condition, or event that causes normal 
processing operations to be suspended temporarily. 


1/0 
See "input-output". 
keytop 
The upper surface of a key on the keyboard, and by 
extension, the printed symbol or name there. 
keyword 


A mnemonic word used in APL keyword form to replace an 
APL primitive. 


keyword form 


The display form in which executable APL is written 
using keywords instead of the special APL symbols. 


label 


A name used to identify a line in an APL function. A 
label, followed by a colon, immediately precedes the 
rest of the statement. Labels are used in branching 
expressions as the values of the lines on vhich they 
appear. 


lamp symbol 
The symbol & used to separate a comment from a 
statement or a label. A comment preceded by a a can 
occupy a separate function line. 

latent expression 
A system variable (DLX) whose contents are executed 
immediately when a workspace is loaded. Represented by 
Dzr. 

left argument 


The value that appears to the left of a dyadic 
function. 
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length 


The number of positions along a coordinate. See "shape 
of an array". 


LENGTE ERROR 


An error condition that occurs vhen an argument to a 
function is not of the appropriate length (along at 
least one coordinate) for use with the function or with 
its other argument. 

library 


A set of stored files and/or workspaces. On the 
APL*PLUS/PC System, equivalent to a DOS directory. 


line number 


In a function definition, the number associated with a 
line. 


linefeed character 


A non-graphic character that, when displayed, causes 
the cursor to advance one line, but does not cause any 
horizontal motion. Represented by UTCLF. 


literal data 
See "character data". 
local definition 


The definition of a function at a particular state of 
function execution. Compare "global definition", "most 
local definition". If an object's name is not included 
in the header of any function in the state indicator, 
its local and global definitions are the same, 


local environment 
The collective name for all of the most local 
definitions of functions, variables, and system 
variables. An APL statement in a defined function can 
only use or modify the local definitions of objects. 
Compare "global environment". 

local value 


The value of a variable at a particular state of 
function execution. 


local variable 


A variable that has a value only during execution of a 
defined function. 
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location 


An element of computer memory referred to by its 
address. 


locked function 


A defined function that cannot be edited or displayed. 
See also "function". 


loop 


A closed sequence of statements performed repeatedly, 
usually until some test condition is met. 


low-level language 


A programming language that is machine-dependent, being 
translated by an assembler into instructions and data 
formats for a specific machine. 


machine language 


The set of processing instructions native to the 
computer hardware, and therefore the only instructions 
the hardware can execute. Commands or instructions in 
higher level languages are translated into sometimes 
lengthy sequences of machine language by system 
software (such as the operating system command 
processor) and various computer language processors 
(such as the APL*PLUS/PC System). 


matrix 


A rectangular arrangement of elements (numbers or 
characters); each element requires two subscripts to 
identify it -- the first identifies the row, the second 
identifies the column. A two-coordinate or two- 
dimensional array; an array of rank two. 


memory 


Any device or medium capable of accepting and retaining 
data, so that data can be retrieved and used when 
needed. Often used more narrowly to refer to the 
computer's internal memory. 

minus sign 
See "subtraction sign", "negative sign". 


mnemonic 


A name or symbol chosen to assist the human memory; for 
example, "fn" for "function". 


Copyright 1983 STSC, Inc. GL-21 System Functions 


modem 


A device that permits the transmission of digital 
signals over analog transmission lines. Acronym for 
modulator-demodulater since it modulates and 
demodulates signals transmitted over communication 
facilities. 


monadic function 


A function that takes only one data argument (appearing 
on its right). 


most global definition 
The definition of a variable or function at the state 
where there are no suspended functions (with a clear 
state indicator). Contrast with "local definition", 
"most local definition". 

most local definition 


The definition of a variable or function at the current 
state of function execution. 


native file 
Any DOS file considered as a stream of bytes and 
accessed with file functions beginning with "JN". 
Contrast with "APL file". 

negative sign 
The sign used to indicate that a number is negative 
(for example, ^8, or in keyword form "8). This sign 
does not indicate an operation. 

newline character 
A non-graphic character that, when displayed, causes 


the cursor to move to the first column in the next 
line. Represented by CTCNL. 


niladic function 
A function that takes no arguments. 
NONCE ERROR 
An error message indicating that the operation is 
well-formed, yet in the current implementation or 
environment (for the nonce) it is not defined. 
non-graphic characters 


Characters in the APL*PLUS/PC System that, when 
displayed, do not have a visual representation. 
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non-negative 
Zero or higher. 
null character 


A non-graphic character that causes no movement of the 
Cursor, but takes the same amount of time as displaying 
a character. Represented by [ITCNUL. 


number 


A quantity. Usable vith arithmetic functions like 
addition. The more limited set of numbers that can be 
Stored in a computer can be expressed as numeric 
constants. Numbers are left unaltered by the APL 
identity function (for example, +5), while characters 
are rejected. 


numeric constant 


A number used directly from the keyboard or within a 
program, but not stored in a variable. It is formed of 
digits with the possible additional use of decimal 
point, negative sign. or even the letter E. A number 
is distinguished from the same character sequence 
within single quotes. 


numeric data 


A collection of numbers. One of the two datatypes in 
APL. See also "character data", "elements", "number", 
and "numeric constant". 


operating system 


An organized collection of software that controls the 
execution of computer programs and that can provide 
scheduling, debugging, input-output control, 
accounting, compilation, storage allocation, data 
management, and other related services; that is, 
manages computer resources and provides services to 
programs. See also "system". 


operator 
À primitive function operating on arguments that are 
themselves primitive functions to create another 
function. For example, the \ in +\ is an operator 
which combines with the primitive scalar afe 
function called addition to produce a primitive monadic 
function called addition-scan. 

origin 


See "index origin". 
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origin-dependent 
Affected by the value of the index origin. 

overstrike 
A composite symbol formed by typing two symbols in the 
same character position. Also by extension, symbols 
that can be formed that way even when they have been 
made available on a single key. 

owner of a file 


The account number by which the file was created or 
most recently renamed, 


parameter 
A value specified for use by a program, software 
package. or DOS command, often from a limited set of 
acceptable values. 

passnumber 
An integer from 32,788 to 32,767 inclusive that can be 
used to extend the identification of a user. Used with 
files to exercise detailed control over file access as 
specified in the access matrix. 

passthrough localization 


Use of global values for localized system variables 
that have not yet been assigned local values. 


pel 
See "pixel". 

pendent function 
A function that is halted because of a suspension in 
another function that is called by this function. 
Pendent functions cannot be edited with function 
definition mode nor changed (under that name) with the 
full-screen editor. 

peripherals 
Devices that can be attached to a computer or terminal 
(for example, printers, disk drives, plotters, or 
microfiche viewers). 

pixel 


A term for “picture element". The smallest graphic 
spot which can be turned on or off independently. 


Copyright 1983 STSC, Inc.  GL-24 System Functions 


precision 


The number of significant digits used to represent a 
number. 


primitive function 


A function built into the APL language and represented 
by a single non-letter symbol in APL symbol form. 


program 


(To develop) a set of sequenced instructions that cause 
a computer to perform particular operations; a plan to 
achieve a problem solution; a routine. See also 

"application program", "function", "operating system". 


programmed function key 
A key which can be programmed to contain or perform 
varying functions; in the APL*PLUS/PC System, the keys 
that can be programmed by [JPFKEY into multiple 
character sequences. 

programming language 
A language designed to express instructions in a form 
suitable for execution by a computer. Examples are 
APL, BASIC, COBOL, FORTRAN, and Assembly language. 
Also called "computer programming language". 

prompt 


A cue given to the user by a computer program asking 
the user to enter information. 


public comment 
A comment at the end of a function line, beginning with 
^ and retrievable even from a locked function by 
DCRLPC. 

quad functions 
See "system functions". 

quad input 
See "evaluated input mode". 

quad variables 


See "system variables". 
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query 


A^ question directed to the user by à computer program, 
or vice-versa, to obtain specific information. 


quote quad input 
See "character input mode". 
radix 


The base number in a number system; for example, the 
radix in the decimal system is 10. 


RAM 


An acronym for random access memory; often specifically 
a memory chip used with computers that can be read from 
and written on. Contrast with "ROM". See also 
“memory”. 


random link 


The link (value of (IRL) used by the system's 
pseudo-random number generator. 


rank 
The number of dimensions (coordinates) of an array. 

RANK ERROR 
An error condition resulting from the use of an array 
whose rank is inappropriate for the purpose; for 
example, failing to match the rank of the other 
argument of a scalar dyadic function. 

read 
To obtain or interpret data from a storage device, data 
medium, or other source. 

reboot 


To reload the operating system and reinitialize all of 
the computer's internal memory, as by system reset. A 
last ditch effort to regain control of the computer 
without powering off and back on. Loses all data in 
Computer memory. See also "bootstrap". 

recursive function 
A function that calls itself during execution. 


Red 


One kind of shift key (sometimes called Alt) for which 
a red keyboard label has been provided. 
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register 


An internal computer component capable of storing a 
specified amount of data (for example, one word). 
Registers hold the results of intermediate 
calculations, 


relational function 


A function used to compare two values that returns a 
result of either 1 or 0 to indicate true or false. See 
also "function". 


reset 


To return components of a computer system to a 
specified starting state. See also "reboot". 


return 


To resume execution in and pass a value back to the 
calling environment (for example. the results of a 
function). 


right argument 


The value appearing to the right of a monadic or dyadic 
function name, 


ROM 


Acronym for read-oniy memory; typically, a memory chip 
used with computers from which data can be read but to 
which no data can be written. Contrast with "RAM". 
See also "memory". 


root directory 
The main directory on a floppy disk or hard disk. 

row (of a matrix) 
A horizontal line of elements in a matrix or array of 
elements. Also, the first dimension of a 
two-dimensional'array or, more generally, the next-to- 
last dimension of any array. 

RS-232 
The most common type of connection into a computer for 
a serial device, such as a terminal, modem, or plotter. 


Its characteristics are determined by a standard from 
the Electronic Industries Association. 
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run 
To execute a particular computer program. See also 
"execute". Also, an execution of a program by a 
computer on a given set of data. Also called 
"execution", See also "execute". 

saved vorkspace 
A workspace stored in a library (on a disk). 

scalar 
An array of rank zero that must contain a single data 
element: a single number, or a single character. See 
also "scalar constant". 

scalar constant 


If numeric, a single number; if character, a single 
character enclosed in quotes. 


scan operator 
Primitive facility that combines with any primitive 
scalar dyadic function to form a new monadic function. 
The new function forms successive elements of its 
result by using reduction to apply the scalar dyadic 
function to successive take (t) operations of the right 
argument. 

scope 
With respect to an active state indicator, the 
collection of contiguous environments (function calls) 
in which a particular definition of an identifier 
persists. 

scroll 
The movement of text on a CRT (screen), 

security 
Protecting data from the wrong people, those who should 
not be allowed to change it, or even see it (payroll 
information, for example). 

seed value 
See "random link". 


session 


A period of time during which a particular software 
system is in continuous use. 
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session-related system variables 
A system variable whose value is not changed by loading 
or clearing a workspace. The values remain through an 
entire session unless explicitly changed. Contrast 
with "workspace-related system variables". 

Shadoved 
An APL object at a particular state of function 
execution that is inaccessible from the current state 
because an object with the same name is localized at 
the current state or at an intervening state. See 
"scope". 

shape of an array 


A numeric vector whose elements are the dimensions of 
the array. 


shared file 

See "file". 
Shift keys 

Keys that alter the effect of pressing a character key. 
Shift keys 


One kind of shift key for which a green keyboard label 
has been provided. 


singleton 
An array containing a single number or character 
regardless of rank. Any elements in its shape vector 
are 1. 

Sink file 
A file into which material destined for display on the 
screen is placed, either in addition to or in place of 
the screen. 


software 
A set of functions, procedures, and routines associated 
with the operation of a computer system. See also 
"hardware", "program", 

source file 


An APL component file used as an input source. See 
"input source". 
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spool 


Acronym for simultaneous peripheral operations on-line. 
To write or read data to or from peripheral devices 
concurrently with execution of another program. For 
example, to spool data that is ready for printing so 
that it is printed while the computer is freed for 
other uses. 


state indicator 
A table in the active workspace that tracks the 
execution progress of defined functions. If function 
execution is halted, the state indicator shows the 
halted defined functions in order (the most recently 
active suspended function first) and the line in each 
function where execution stopped. 

statement 
A syntactically well-formed expression of APL primitive 
functions and operators, data constants, variables, and 
user-defined functions. 

statement label 
See "label". 

steward 
The individual or user account number that can add, 
delete, or modify the access of other user account 
numbers to a particular software application. 

stopping 
The use of the system function [ISTOP to cause function 
execution to halt before executing specified function 
lines. 

store 


To enter data into or retain data in a device from 
which it can be retrieved at a later time. 


strong interrupt 
Exit or two or more BREAK's entered in quick succession 
during processing. A strong interrupt is recognized 
during the execution of an APL statement, and may halt 
execution before the entire statement has completed. 
Contrast vith "weak interrupt". 

subprogram 


Synonym for "subroutine". 
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subroutine 


A subsidiary routine that is expected when called by 
some other program, usually the main program. Also 
called "subprogram", 


subscript 
The value used to indicate the specific position(s) 
along a given coordinate of an array. Also called 
"index". 

subtraction sign 
The sign used to indicate that the subtraction function 
is to be performed (for example, 5 - 3); represented by 
the hyphen. 

suspended function 


A function whose execution has been halted at some 
point because of an error, a BREAK signal, or a stop 
set by (STOP. Suspended functions are marked in the 
state indicator by a +. See "state indicator". 


Suspended workspace 
A workspace whose state indicator is not empty. 
symbol form 
The display form in which executable APL is written 
using APL symbols rather than their keyword 
equivalents. 
symbol table 


The area of a workspace that stores the names of APL 
Objects that have been referred to in the workspace. 


syntax 


In APL, the rules by which functions and their 
arguments are put together to form valid statements. 


SYNTAX ERROR 


An error occurring from an improperly formulated 
expression or an improperly called function. This may 
be caused, for example, by unmatched parentheses, by 
two variables juxtaposed with no function between them, 
or by a function used without correct arguments as 
specified in the function header. 
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system 


The physical equipment and software used as a unit to 
process data. A system includes the central processing 
vnit, its operating system, and the peripheral devices 
and programs under its control. 


system command 


An instruction used to direct the APL*PLUS/PC System in 
performing certain housekeeping tasks; an instruction 
that allows the user to monitor and control the 
contents of workspaces, files, and libraries. Every 
system command begins with a right parenthesis. System 
commands cannot be used as part of an APL statement or 
defined function. 


system constant 


A constant value that is available from the system 
(like a system variable), but that is not 
user-definable. 


system functions 


A special class of functions that can always be used 
from the active workspace. They occupy no storage in 
the workspace and do not appear in the )FNS list. 
System functions have names beginning with the quad 
symbol (Č). Some system functions perform operations 
similar to system commands. 


system variables 


A special class of variables, always in the workspace, 
that are used to monitor or control the workspace or 
session environment. They are distinguished by having 
names that begin with the quad symbol (J). See 
"workspace-related system variables", "session-related 
system variables". 


thorn symbol 


The symbol y used to represent the format primitive 
function. 


tie 
To assign a unique integer to a file to allow for 
referencing the file when it is in active use. Also, 
the match of file to tie number so created. 


tie number 


See "file tie number". 
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timestamp 


A record of the óate and time that some event occurred 
(for example, appending a file component). 


e tracing 


type- 


The use of the system function DTRACE to display the 
result of statements on specified lines. 


ahead buffer 


An area in memory where typed keystrokes are collected 
until the system is ready to process them; if the 
type-ahead buffer is full and additional keystrokes are 
received, the APL*PLUS/PC System will beep to indicate 
loss of the trailing character(s). The type-ahead 
buffer is cleared by Exit or BREAK, but not by an error 
halting an earlier statement or running program. 


unbalanced quotes 


An odd number of quotes (not counting any quotes in the 
optional comment) in an APL statement. 


unconditional branch 


g user 


user- 


A branch statement whose effect is always the same, 
Contrast with "conditional branch". 


account number 

The unique integer used by an APL*PLUS System to 
identify a user. The user account number is the value 
of 1'D4v. 

defined function 


See "defined function". 


value 


Data that can be assigned to a variable; specific data, 
either a constant, the contents of a variable or system 
variable, or the explicit result returned by a 
function. 


VALUE ERROR 


An error occurring when an executing expression finds 
no value provided where one is needed; for example, 
trying to use the explicit result of a function that 
produces none. Evaluated input (D) reports a VALUE 
ERROR when the user's statement does not return an 
explicit value and reprompts. 
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value potential 


The indication of whether an APL statement returned a 
value. One of the three potentials associated with an 
APL statement after it has executed. Compare "branch 
potential" and "display potential". 


variable 
A named collection of data; à named array. 


vector 


A linearly arranged array; an array with one coordinate 
(dimension); an array of rank one; a data structure 
that permits the location of any item by the use of a 
single index or subscript. See also "atomic vector", 
"empty vector". 


visual representation 


The form of display of a defined function that includes 
leading and trailing del symbols (Y) and line numbers. 
The result of (WR. 


waiting function 


A function called in the currently executing APL 
statement vhose left argument is being evaluated prior 
to beginning the function. 


weak interrupt 


A single BREAK entered at the keyboard. A weak 
interrupt is recognized only at the completion of a 
line of a function. Contrast with "strong interrupt". 


vindow 


A rectangular portion of the CRT screen, specified by 
four integers: how many lines and columns to skip from 
the upper left-hand corner of the screen to locate the 
upper left-hand of the window, and the shape of the 
window (number of rows and of columns). 


workspace 


The APL execution environment in which computation 
takes place and in which names have meaning. A 
workspace contains the variables, defined functions, 
and control information for an APL session. A 
repository for a collection of functions and data. 
Workspaces can be stored in libraries for later use. 
See also "active workspace" and "saved workspace". 


workspace parameter 


See "system variables". 
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workspace identification 
The library number and name that identify a workspace. 

workspace-related system variables 
System variables that are associated only with a 
workspace. Their value is not preserved when another 
workspace is cleared or loaded, or when an APL session 
ends. See also "session-related system variables". 

wrap 
TO continue uninterrupted on a second line of the 
screen a line begun above. Also, the name of the key 
used to declare the current line to be a continuation 
of the line above. 

wrap marker 
The screen attribute used in the leftmost column of the 
current window to indicate that the line on which it 
Occurs is part of a wrapped line begun above. 

wrapped line 
A line on a CRT screen that is longer than the width of 
the screen. The display of a wrapped line occupies 
more than one physical line on the screen or continues 
on the line or lines below its beginning. 

zilde 


Name of the symbol 6 and, by extension, of the empty 
vector it represents. 
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COMPREHENSIVE INDEX 


This index contains references to these manuals: 


A. Installation Manual 

B. User's Guide 

C. APL Is Easy! 

D. Formatting User's Guide 

E. File System User's Guide 

F. Programmer's Manual 

G. System Functions, System Variables. and System 
Constants 


Each of the page references in the index begins vith 
the letter from the above list, identifying the referenced 
manual, After the initial letter, the pages are referenced 
as they appear in each book. If there are two letters, the 
Second letter refers to an appendix instead of a chapter. 


Some of the manuals have separate indexes that may 
contain entries not in this list. 


The system functions, system variables, and system 
constants are arranged alphabetically in System Functions, 
and therefore are self-referencing. 


4 format phrase. D5-5 to 
6, D5-32 
APL startup option, 
B1-5 
abs, Fi-8 
Absolute tabbing, D5-10 


to 11, DS-13 
Absolute value, F1-9 
Access 
defined, 
Access codes, 
Access matrix, 
codes used in, 
defined, E3-2 
examples of, E5-2 
overriding, ES-3 
reading, Ew-1 
rules pertaining to, 
ES-1 
Setting, E4-1 
treatment of file 
owner, E5-1 
Account number, see User 
account number 
Accounting information, 
G3-2 
Active workspace, see 
Workspace, active 


E1-2 

E4-2 

E5-2 
E4u-2 


Adapter, B1-1 
AMDEK, G3-128, G3-130 
AT&T, G3-131 
Hercules, A2-4, G3-128 


to 130, G3-144 
IBM color, A2-1, 
G3-127 to 128 
IBM Enhanced Graphics 
(EGA), A2-1, 
G3-126 to 132.1 
IBM monochrome, A2-1 
non-IBM, A2-2, G3-127 
to 132.1 
ORCHID, G3-126 to 127, 
G3-131, G3-144 
SCION, G3-126, G3-131 
TECMAR, G3-130 to 131 
Add, ¥F1-8.1 
Adding data to a file, 
Ei1-5, G3-69, G3-103 
Advanced formatting 


techniques, DD-1 
to 12 
DAI. 63-2 
Aids to formatting, Dé-1 
to 8 
Alphabet 
lowercase, B&-5, Fi-2 
underscored, Fi-2 


Copyright 1984 STSC, Inc. 


-i1- 


Alphabetize, F1-22.1 
details on, P1-60 to 62 


Alt key. B2-2, B2-3 
extra, G3-235 
pressed to slow output, 
B2-11 


used with End, B2-8.1 
used with Home, B2-8.1 
usel with Left, B2-8.1 
used with Right, 
B2-8.1 
used with Scrolls, 
B2-8.2, B2-9 
used with Scrollt, 
B2-8.2, B2-9 
used with unified 


keyboard, B2-4 
Alternate row formatting, 
D5-31 


DALY, G3-3 to 4 
Ambivalent functions, 
F1-6, F1-41 
see Adapter, 
AMDEK 
and, C51 to 53, Fi-12 
APL characters (symbols), 
see Character set 
APL files 
characteristics of, 
E1-2 
vs. native files, 
E1-10, E7-1 to 5 
APL instruction, B10-2 
APL keyboard state. see 
Keyboard states 
APL keyword form, see 
Keyword form 
APL keywords, see 
Keywords 
APL language 
summary, F1-1 
APL library, see Library 
APL session, 


AMDEK , 


starting, A3-13, B1-3 
APL startup options, 
Bi-4 to 8 
APL symbol form, B6-2. 
P2-19 
selecting under program 
control, 
G3-242.1 


APL symbols 
on the screen, A2-1 


APL system disk, 81-1 to 
3 

APL users groups, B11-1 
to 2 


Comprehensive Index 


APL.EXE file 
modifying, B1-11 
APLLIBS file, 3-12, 
B1-2, E6-3 to 4, 
F2-22, G3-188 
effect on INCREATE, 
G3-200 
APL*PLUS/PC special 
formatting 
considerations 
Boolean values, D2-5 
display in exponential 


format, D2-6 
field width, Dy-2, 
Di-4, D5-8 
format pairs in dyadic 
format, D4-s 
)GROUP system command, 
D6-1 


internal representation 


of numeric data, 


D2-5 
maximum data list in 
OFNT, D5-3 


mingling integers and 
floating-point 


data in matrices, 


D2-8 


using C and 2 modifiers 


together, 
value of JPW, 
/ as delimiter, 
APL*PLUS/PC System 
installing Software. 
A3-1 to 14 
special keys, list of, 
B2-3 


DS-27 
D2-2 
D5-u 


Apostrophe, Fi-1 
ZARBIN, B3-1, B7-2, 


F5-8, FB-i, G3-6 to 


12 
cursor display, G3-237 
"don't wait” 

single-character 
input, G3-174 
keystrokes display, 
63-235 
translation types, 
B8-3 
used to create a 
character set on 
printer, Ba-3 
used to separate 
overstrikes into 
components, 
B8-4, B8-5 
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used with Z=16 startup 


option, B1-10 

used with graphics 
mode, B9-1 

used with jINBUF, 
63-173 

used vith serial ports, 
B8-3 

Apricot computer, B1-5 


Arbitrary input, see 


DARBIN 
Arbitrary output to 
screen, see [ARBIN 


and DARBOUT 


ÜARBOUT, FB-1, G3-13 
of empty vector, F1-37 
Arc (graphics), see 
ÜGCIRCLE 
Argument 
defined, C21, Fi-6 


of a defined function, 
C72 to 74, F1-41 
Array, Fi-1 to 2 
display of, D2-6 to 9 
empty, F1-3 to 4 
maximum size of, F1-2 
ASCII 
character set, 87-2 
transmission codes, 
PB-4 
^ASF file extension, 
F2-20, G3-200 
Aspect (graphics), 
63-143 
ratio with [GCIRCLE, 
63-122 
Assembly language, see 
DCALL 


Assemply language 


functions, F6-3 to 
26 
Assignment, F1-26, F1-38 
indexed, F1-26 


Atomic vector, see (V 
Attribute, video, 
63-286, G3-291 to 2 
interpretation of, 
63-236 
placed on screen by 
DWPUT. G3-291 
read from screen by 
DWGET. 63-286 
in scrolling memory, 
63-177, B1-S 
selecting with OPOKE, 
63-236, G3-240 
values for color and 
monochrome, 
G3-287 
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AUTOEXEC.BAT file, 
FS-1, FC-1 
creating vith EDLIN, 
A3-5, A3-10 
Automatic repeat of typed 
Characters, B2-6 
DAY, FA-1 to 7, G3-14 
.AW$ file extension, 
F2-20,63-200 


Bi-3, 


B modifier with OFNT, 
D$5-1? 


used in combination, 
D5-26, D5-28, 
D5-28 
Background fill with 
DFMT, D5-22 to 23, 
D5-28 to 30 
Backspace character, see 
DTCBS 
Back-up copy, 
of a disk, 
A3-12, B5-1 to 2 
of a file, E2-7 
Banner, session startup, 


G3-174 
programs run from APL, 
G3-27 
Base value, F1-23 
BEL (ASCII), see [TCBEL 
Binomial coefficients, 
F1-10 
BIOS 
controlling RS-232 
port, B1-10 
controlling screen 
output, Bl-1i 
Bit-pairing, PB-3 
Blank line 
inserting on screen, 
B2-8, B2-13 
Blank modifier with DFMT. 
D5-1? 
used in combination, 
DS-26, D5-28, 
Ds-29 
Blinking characters, see 
Attribute, video 
Boolean, D2-5, F1-31 
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Boundary 
for data display, see 

URINDOW 
for graphic display, 

see DGVIEW 
for graphic fill, 

G3-140 

Brackets, F1-38 
Branch, C124 to 125, 
C133, Fi-4, F1-38, 
F1-45 
conditional, C124 
niladic, Fi-46 
with empty vector, 
Fi-4 
B2-3, B2-10, 
B2-12, B7-3, C15, 
C127, C121, Fi-43, 
see also Strong 
interrupt and Weak 
interrupt 
disabling/enabling, 

G3-236 
during Hold, 82-11 
in HELP facility, B4-2 
limiting strength, 

G3-236 
simulating, G3-236 
with Shift Print, B8-6 
in terminal mode, B7-3 

BS (ASCII), B?-3, see 
also UTCBS 
Buffer 
C= APL startup option, 

B1-5 
communications, see 

Communications 

buffer 
H- APL startup option, 

B1-6 
screen scrolling, 

B1-7, G3-26 
OSOUND, G3-258 
type-ahead, see 
Type-ahead buffer 
see Reporting 

system bugs 
Built-in speaker, see 
Speaker, built-in 


BREAK, 


Bugs, 


C modifier with DFMT, 
D5-18, D5-29 

C- APL startup option, 
B1-5 
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DCALL, G3-15 to 21 

assembler input call, 
G3-235 

assigning variables 
with, G3-16 

compared to DINT, 
63-176 

erasing objects with, 
G3-18 


utility functions, 
F6-6 
Canonical representation, 
Li 


see 
UCAP, G3-22 to 24 
CapsLock key, B2-3, B2-4 
poking, 63-237 
CAPTURE function (for DOS 
output), 63-26 
Capture sink, G3-22, 
G3-181 
catenate, C18, C30, 
C122, Fi-16 
ceiling, F1-9 
CENTER function, 
D6-2, D6-6 
Centering titles, 
D6-2, D&-6 
Chaining workspaces, 
63-195 
Changing a file's size 
limit, E2-6, 
63-106 
Character 
blinking, see 
Attribute, video 
count for input and 
output, see DAI 
Character data 
defined, C28 
display of. Di, D2-3 
format phrase for, 
D5-5 to 6 
Single quote within, 
c28 


Dé-1, 


D6-1, 


Character input, B3-1, 
B3-3, C120, F1-33, 
G3-6, G3-57 

counted, see [jar 
escaping from, C121, 
see also Exit 


mode, B3-1, B3-3 
single character, see 
ÜINKEY 
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Character ROM 
and static electricity, 
A2-10 
installing, 
to 12 
installing in COMPAQ, 
A2-8 
Character set, 
FA-1 to 7 
downloading to EPSON 
FX, A3-14 
for line drawing, see 
Line, -drawing 
characters 
programmable (soft), 
A2-1, B1-8 
Character string search, 
see Oss 
CHDIR (DOS command), 
E6-2 
Check protection, 
Chirp (bell) 
from remote computer, 
G3-269 
with DPOKE, G3-237 
CHKDSK (DOS command), 
F5-11, FC-2 
Circle (graphics), see 
UGCIRCLE 
Circular functions, 
Fi-11 
Cleaning disk drives, 
B5-1 
CLEAR, F2-4 
Clear screen 
on personal computer, 
see ?CFF and 
Home, with Alt 
transmit to remote 
computer, B7-4 
Clock, system, G3-2, 
G3-49, G3-96, 
G3-280, G3-299 
current time from, see 
ars 


A2-1, A2-3 


A2-2, 


DS-29 


setting system, G3-177 
Closing a disk file, 
B1-2, E1-?, E1-10 
CM, Fi-13, F1-28 
)CMD, E1-8, E2-6, F2-5, 
FC-1 


ZCMD, FC-i, G3-25 to 28 


COLNAMES function, D6-1, 
D6-4 
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Color 

attributes, see 
Attribute, video 

graphic areas, see 
GPAINT and 
UGS#ADE 

graphics characters, 
see [IGWRITE 

regular characters, 
see Attribute, 
video 


Column names, D6-4 


Columns of data, C18, 
D4-2 
Combinations 
of elements in a set, 
F1-10 


of modifiers with CFMT, 
D5-26, D5-28 to 


29 
combine, F1-10 
Combined editing vith 

JFMT, D4-5 to 6 


Comma modifier with OFMT, 
D5-18, D5-29 
COMMAND.COM file, 
F2-6, G3-25 
Comment, C127, F1-39, 
F1-52.1, G3-35 
public, F1-42.1 
Communications,  F5-8, 
F5-12 to 14, see 
also GARBIN 
buffer, see 
Communications 
buffer 
buffer contents lost 
during [CMD or 
)CMD, 63-26 
with XON/XOFF, see 
XON/XOFF protocol 
Communications buffer, 
B1-5, G3-5 
buffer size, Bi1-5 
C= APL startup option, 
B1-5 
Compacting a file, 
to 8, see also 
CFDUP 
COMPAQ 
installing character 
ROM in, A2-2, 
A2-8 


F2-S, 


E2-7 
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Comparison of 
QDEF with OFX, G3-45 
DERASE with DEX, G3-63 
QFMT with dyadic v, 
DB-1 to 2 

DIDLIST with DNL, 
G3-167 

DIDLOC with DNC, 
G3-169 

)LIB with [LIB, F3-186 

Comparison tolerance, 

see IcT 

Components 
arrangement in files, 

C107, E1-3 
defined, C106 to 107, 
E1-1 
information about, 
E3-4 
number of, in a file, 
E2-3 
size limitations, E1-2 
timestamp, E3~4, E7-4, 
G3-96 
Compress function, C49, 
C53 to 54, Fi-19 
Compressing data files, 
B5-2, G3-77 
COMSPEC= DOS parameter, 
F2-5, G3-26, G3-28 


COMSWAP, FS~14 

COMI serial port, B1-5, 
B7-1, F5-14, G3-5 

COM2 serial port, 'B1-5, 
F5~14 


Concurrent data reception 
0) 


with DARBIN, G3-9 
not with [CMD or )CMD, 
G3-26 
with terminal mode, 
B7-1 
CONFIG.SYS file, EC-1 to 
2, F2-8, G3-31 
Connected lines 
(graphics), see 
UGLINE 
Constant, Fi-1 
character, Fi-1 
Continuation of screen 
line, see Wrapped 
line 
Control 
of execution, see 
Execution, 
control of 
of file size, see File 
size, control of 
G3-177 
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Coordinate, F1-2 
COPY 
DOS. FC-2 
)COPY, F2-7, F2-25 
DcoPY, G3-29 to 31 
effect on JS70P, 
OTRACE. 63-133 
Copying 
data, Ei-9 
a file, E2-7, 63-7? 
unless name in use, 
P2-27 
a workspace, B1-2 
Cosine, Fi-11 
COULD NOT RETIE ALL 
FILES, F2-5, G3-25 
count, F1-21 


ICR, G3-32 
CR (ASCII), B7-3, see 
also DTCNL 


Creating a file, Ei-5, 
63-72, G3-200 
Credit and debit 
notation, D5-30 
DCRL, G3-33 to 34 
DCRLPC, G3-35 
DCRT, G3-36 to 37 
CSSMAT function, G3-19 
CSSMATML function, G3~21 
DCT, G3-38 to 40 
Ctrl key, B2-2 
extra, G3-235 
used with arrow keys, 
2-5 
used with Delete, B2-8 
used with End, 82-7 
used with Home, B2-7 
used with Scrolls, 
B2-9 
used vith Scroll*, 
82-9 
used with Tab, B2-7 
Ctrl N, B7-4, B7-6 
Ctrl O, B7-4, B?-6 
Ctrl Q, B2-11, B8-3 
Ctrl S, 82-11, B8-3 
Current directory, E6-2 
ÜCURSOR, 82-7, G3-41 to 
42 
Cursor 
changing size of, 
G3-237 to 238 
movement, B2-6 to 7, 
G3-41 
pad, 52-2, B2-3, B2-4 
position of, F3-11, 
G3-41 
turning on and off, 
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Curve 

fitting vith E, F1-57 
Custom titling of 

reports, D&-7 to 8 


Data, C6 
in native files and APL 
files, 57-1 
loss of, 57-4 
verification of, G3-85 
Data Terminal Ready, see 
DTR 
Datatype, Fi-1 
conversion, G3-54, 
G3-84, G3-209 
identifying, G3-54 
Date, system 
reading, see Ors 
setting with )CMD DATE, 
see DATE, DOS 
command 
setting from DOS, see 
DATE, DOS command 
setting with "INT, 


63-177 
DATE 
DOS command, FC-1, 
PC-2 


deal, Fi-14 
Debugging functions, see 
ODSTOP and [ITRACE 
Decimal format, D2-5 
Decimal position 
parameter, D5-14 
Decode, F1-23 
Decoration with DFMT, 
D5-19 to 22 
DDEF, G3-43 to 45 
effect on DSTOP, 
DTRACE, G3-44 
vs. OFX, G3-45 


Default 

disk drive, changing, 
G3-238 

environment, 
overriding, 
B1-11 

formatting with monadic 
Y. DE-1 


library, defined, E1-2 
library, explained, 
B1-2, E6-1 to 2 
width for dyadic v, 
D4-6 to 7 
ÜDEFL, G3-46 to 48 
DEFN ERROR, C66, C73, 
€127, F3-6, F3-18 
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DEL (ASCII), B?-3, see 
also [ITCDEL and 
Delete key 

Delay execution, see [DL 

Delete key, B2-? 

in terminal mode, B7-4 
used with Ctrl, B2-8 

Deleting 

Characters, B2-8,1 to 


8.2 
files, E1-9, F2-10. 
FC-3, G3-81, 
63-203 
Delimiters 
with (FMT, DS-3 
with a HELP Menu, Fa4-2 
Detached 1/0, see (CAP, 
DIN, DIOSTATE, and 
Dort 
Diagnostic message, last, 
see DDM 
Dimension, F1-2 
Directory 
design of a HELP, F4-8 
disk, E6-1 to ^ 
searching a HELP, F4-4 
Disk drive, Bi-1 
double-sided, A3-2 
hard, A3-7 
Disk file 
defined, E1-2 
DISK FULL, E1-6, F2-31, 
F5-10 
DISK WRITE PROTECTED, 
F2-10 
Display 
arrays of rank 3 or 
more, D2-6 to 9 
attributes, see 
Attribute, video 
matrices, D2-6 to 8 
scalars, D2-6 
vectors, D2-6 
Dithering (graphics). 
G3-137, G3-140, 
G3-145 
divide, F1-9 
DDL, G3-49 to 50 
ODM, Fi-43, G3-51 to 53 
in keyword form, 
G3-183 
clearing contents of, 
G3-66 
do, F1-27, F1-47 
DOMAIN ERROR, C30, C39, 
c50 
defined, C29 
formatting, Da-7, DA-1 
to 2 
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Domino, F1-55 
DOS. Bi, Bl-1, Bi-3, 
81-5, Bl-6, Bi-8, 
F2-5, FC-1 to 3 
commands from APL, see 
)£MD and DCMD 
controlling keyboard, 
B1-8 to 10, G3-26 
directory as APL 
library, see 
DLIBS 
ending a session, Bi-« 
file extensions, E1-4 
getting into, 3-2, 
Ài-8 
returning to, Bi-4, 


version 3.1, Bi-6, 


DOS COMMAND FILE NOT 
FOUND, F2-6, G3-27 

Dot product, F1-29 

Double-sided, see Disk 
drive, double-sided 

Down key, 82-5 

in terminal mode, 87-3 

downgrade, F1-23, Fi-58 

DDR, F1-5, G3-55 to 56 

drop, Fi-15 

)DRÓP, F2-10 

Dropping file components, 
E2-2, G3-75 


DTR 
reversing status of, 
G3-18 
Duplex 


full/half, setting with 
DPOKE, G3-238 
Duplicating a file, 
E2-7, G3-77 
Dyadic 
defined, C21, Pi-6, 
Pi-41 
Dyadic format, D4-1 to 7 
combined editing, 


DwW-S, D4-6 
comparison with [FMT, 
DB-1, DB-2 
default width, D4-6, 

D4-7 
DOMAIN ERROR, D4-7, 
DA-1, DA-2 


e, base, Fi-10 
E format phrase, D5-7 to 
8 
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E= APL startup option, 
Bi-5 to 6, B1-8 to 
11 
identifying with JPEEK, 
G3-242.4 
CEDIT, B3-6, G3-57 to 58 
JEDIT, B3-6, F2-12 
Editing, F3-1 
functions, with the del 
editor, F3-1 
functions and character 
variables, see 
Full-screen 
editor 
numeric arrays, see 
Numeric editor 
Element, F1-2 
Ellipse (graphics), see 
DGCIRCLE 
DELX, G3-S9 to 61 
not executed with DIN, 
63-172 
not executed during 
HELP, G3-161 
Empty, Fi1-3 
character vector, Fi1-3 
matrix,  F1-35 
numeric vector, F1-3 
Encode, F1-24 
End, 82-5 
with Alt, B2-8.1 
with Ctrl, B2-7 
Ending a session, Bi-3 
Environment 
calling, F1-43, see 
also State 
indicator, )SINL 
hardware, see Hardware 
environment 
non-IBM, B1-8 to it 
software, see Software 
environment, 
system 
epower, Fi-10 
EPSON printer 
APL characters on, 
A3-14, B8-3, 
G3-8, G3-11, 
G3-242.5 
graphics displayed on, 
G3-131 to 132, 
see also IGPRINT 


Equal 
defined 
(mathematically), 
63-39 
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function, C49, Fi-11 
influenced by fcr, 
G3-39 
ERASE (DOS command), 
FC-3 
)ERASE, C98 to 99, 
F2-18, F5-11 
DERASE, G3-62 to 63 
vs. JEY, G3-63 
Erasing 
characters, see 
Deleting, 
characters 
files, E1-9, see also 
JFERASE, DWERASE, 
)DROP, and ERASE 
(DOS command) 
functions and 
variables, see 
JERASE, ERASE, 
LEX 
objects with DCALL, 
G3-62 
ERROR, G3-84 to 66 
Error 
handling, see 
Exception 
handling, errors 
most recent, see [DM 
Signaling, see ERROR 
trappable, list of, 
63-59 to 60 
untrappable, list of, 
G3-60 to 61 
user-defined, see 
TERROR 
Error message, see also 
Error reports 
custom, see [ERROR 
most recent, see [DM 
recorded, see DDM 
Error reports 
file, EA-1 to 3 
formatting, DA-1 to 2 
ESC (ASCII), B?-4, B7-6, 
see also CICESC 
Escape 
in terminal mode, B7-4 
Evaluated input, B3-1, 
B3-3 to 4, C120, 
F1-32 to 33, Fi-43 
escaping from, Ci21, 
see also Exit 
explicit result of, 
F1-33 
mode, B3-1, B3-3 to 4 
with o, F1-33 
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Evaluation 
order of, F1-38 
Exception, defined, 
G3-51 
Exception handling 
attention, see [ALY 
and 0S4 
see DELI and 
[ERROR 
Exclusive or, 
Execute 
and its calling 
environment, 
F1-50 
explicit result of, 
FI-48 to 49 
primitive, details on, 
Pi-47 
primitive function, 
P1-27, Fi-43 
Execution 
control of, 
Fi-45 
terminating, F1-46 
EXIT (with )CMD), F2-5 
Exit key, B2-3, B2-7, 
B2~11, B3-1, F1-32 
disabling, G3-236 
with graphics 
functions, 
in HELP facility, 
Bu-2, Ba-3 
with KwHelp, B6-6 
limiting strength of, 


error, 


F1-12 


Fi-43, 


B9-1 


G3-236 
simulating, G3-236 
Expand, F1-18 
Explicit result, C74 to 
76, Pinal 
of evaluated input, 
F1-33 


of execute primitive, 
F1-48 to 49 
vs. implicit output, 


Fi-6 
Exponent, D2-5 to 6, 
F1-10 
Exponential 
formatting, D4-4 to 5. 
D5-7 to 8 
function, F1-10 
Exponential format of 
output, D2-5 to & 
rounding, D2-5 to 6 


type of numbers always 
displayed in, 
D2-6 to 8, DE-1 
Expression, Fi-5 
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F format phrase, D5-7 

F- APL startup option, 
B1-6 

identifying with a 
JPEEK. G3-239 

DFAPPEND. E1-5 to 6, 
G3-88 to 70 

OFAVATL, G3-71 

IFCREATE, E1-5, G3-72 to 
74 


OFDROP, E2-2, E2-4, 
G3-75 to 76 


OFERASE, 
82 
FF (ASCII), B7-4, see 
also [TCFF 
JFHOLD, G3-83 
UFI, Fi-48, G3-84 to 86 
Field (formatting), D4-1 
Field width, D4-1 
E editing, D5-7 to 8 
F editing, D5-? 
I editing, D5-6 
FIFO file organization, 
E2-3 to à 


Ei-9, G3-81 to 


File 
APL, E1-2, F2-15, 
G3-87 
compaction, 
G3-77 


component information, 
G3-96 


F5-10, 


creating a, G3-72, 
G3-200 

default file tie quota, 
Bi-6 

defined, Ei-1 

directory, 
user-designed, 
C133 

dropping components 
from a, G3-75 

duplication, G3-7? 

erasing a, G3-81 

errors, 51-4, EA-1 to 
3 

functions, 
characteristics 
of, E1-3 


functions, examples of. 
C107 to 112 

growth increment, 
setting size of, 
G3-235 

handle, EC-1 to 2 
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identification, 


defined, Ei1-5, 
63-72 
input source, 3-170 
library listed, E1-8, 


72-15, F2-20, 
63-87, G3-186 
locating APL, F2-15, 
G3-87 
names of tied, 
G3-92 
native vs. APL, 
E?-1 to 5 
number of components in 
a, G3-108 
operations, defined, 
E1-3 
owner, E5-1 
reading access matrix, 
G3-94 
reading data from a, 
G3-98, G3-209 
renaming a, G3-100 
replacing data in a, 


E1-4, 
E1-10, 


G3-103 
reservation, G3-72, 
G3-108 
resizing a, G3-106 
security, E4-1 to ES-3 


setting access matrix, 
63-111 
sharing, E3-1 to B4-5 
Size, control of, 
B5-2, G3-72, 
G3-77, G3-106 
size limit, E1-3, E1-6 
storage allocated, 
63-109 
storage allocation, 
63-72 
storage occupied, 
63-109 
temporary, 63-78 
tie, duration of, E1-8 
tie numbers, E1-4, 
E1-7, G3-93 
tie quota, B1-6 
tying a, G3-113 
untying a, G3-119 
FILE ACCESS ERROR 
message, E3-2, 
Ea-2, ES-2 
FILE FULL message, El-6, 
E2-6 to 7, E7-2 
File system 
advantages of, E1-1 
general capabilities, 
E1 
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FILE TIED, F2-32 
FILEAID workspace, E3-3 
to 4, E5-3 
FILERELPER program, E5-3 
POKE for, G3-239 


FILES UNTIED,  F2-26 
Find, B6-9, B6-10, 
F1-20.1 
Fixed-point editing, 
Da-3, D5-7 
DFLIB, E1-8, G3-87 
setting vidth of 
result, G3-236 
E1-9, F2-15 
Fi-4, 


)FLIB, 
Floating-point, 
P5-6 to 7 
coprocessor on/off, 
63-235 
data transmission, 
G3-55 
IEEE, see QDR 
rounding error, 
floor, Fi-9 
LFMT. D5-1 to 32, G3-89 
to 91 
A format phrase, 
D5-6, D5-32 
absolute tabbing, 
D5-10, DS-11, 
D5-13 
advanced techniques, 
DD-1 to i2 
B modifier, D5-17, 
D5-28, D5-28, 
DS-29 
background fill, 
D5-22, D5-23, 
D5-28 to 30 
blanks in result, 
D5-17, D5-26, 
D5-28, D5-29 
C modifier, D5-18, 
D5-29 
character editing. 
DS-5, DS-6, D5-32 
comma insertion, 
D5-18, D5-29 
comparison vith dyadic 
format, DB-1, 
DB-2 
delimiters, D5-3 
E format phrase, 
Ds-8 
exponential editing, 
D5-7, D5-8 
F format phrase, D5-7 
field width, D$5-5 


G3-38 


D5-5, 


D5-?, 
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fixed-point editing, 


format zeros as text, 
D5-20, D5-26 to 
28 

G format phrase, D5-8 
to 10, D5-19 to 
23 


1 format phrase, D5-6 

integer editing. Ð5-6 

K modifier, D5-18, 
D5-19, DS-32 

L modifier, D5-18, 
D5-27 

left justify, D5-18, 
D5-27 

M modifier, D5-19, 


D5-20, D5-21, 
D5-27 to 29 
N modifier, D5-20, 
D5-21, D$-28, 
DS-29 
negative left 
decoration, 
D5-19 to 20, 
D5-21, D5-28, 
D5-29 
negative right 
decoration, 
D5-20, DS-21, 
D5-28, D5-29 
0 modifier, D5-20, 
D5-26 to 28 
P modifier, D5-21, 
D5-26 to 31 
parameters, D5-13 to 
15 


pattern editing, D5-8 
to 10, D5-18 to 
23 

positive left 
decoration, 
D5-21, D5-26 to 
31 

positive right 
decoration, 
D5-21, D5-22, 
D5-26 to 31 


@ modifier, Ds-21, 
D5-22, D5-26 to 
31 

R modifier, D5-22 to 


23, DS-28 to 30 
relative tabbing, 
D5-11, D5-12, 


D5-16 
S modifier, D5-23 to 
25. D5-32 
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scaling, DS-18, D5-19, 
D5-32 

stars in result, D5-6, 
D5-15, D5-32, 
DB-1, DB-2 

string construction, 

string processing, 
Ds-4 

summary, G3-89 to 91 

symbol substitution, 
D5-23 to 25, 
D5-32 

syntax, D5-1 to 3 

T format phrase, D5-10 
to 11, D5-12, 
D5-13, D5-15 

text insertion, D$-11 
to 13, D5-15, 
D5-19 to 22 

X format phrase, 
to 12, D5-16 

Z modifier, D5-25, 
DS-26, D5-27 

zero fill, D5-25, 

D5-26, DS-27 

E2-1, G3-92 

GFNUMS, E2-1, G3-93 

JENS, F2-16 

Folded lines with DFMT, 
D2-2 

Font types, differences 
between, D3, 
D5-20, D5-24 


D$-11 


DFNAMES , 


Form 
Changing between APL 
symbol and 
keyword, 
G3-242 
Format, D$-1 to 32, see 
also DFM? 
decimal, D2-S 
exponential, 
integer, D2-5 
pair, Di-i, Dà-2, Da-3 
vector, D4-2, Du-3 
FORMAT 
DOS command, B1i-2, 
B5-1, FC-3 
the workspace, 
format (v) 
applications, 
D3-3 
combined editing, 
D4-5, D4-6 
comparison with OFNT, 
DB-1, DB-2 


F2-19, 


D2-5, 


D6-1 


D3-2, 


Comprehensive Index 


default width. 
Da-? 

dyadic, Da-1 to 7 

monadic, D3-1 to 3. 
DE-1 

shape of result, 
D3-2 

stars in result, D4-7 

syntax for dyadic, 


D4-6, 


D3-1, 


Du-1 
syntax for monadic, 
D3-1 
underscores in result, 
D4-8 


zeros in result, Dà-8 
FORMAT ERROR (error 
message), D5-17, 
D5-25, DA-1 
Format phrase 
A, D$-5, D5-6, D5-32 
absolute tabbing, 
D5-10, DS-11, 
D5-13 
character editing, 
D5-5, D5-6, D5-32 


E, D5-7 

exponential editing, 
Ds-7? 

F, D5-7 

fixed point editing, 
D5-7 

6, DS-8 to 10, DS-19 
to 23 


I, DS-6, DS-11 to 13, 
D5-16, D5-17, 
D5-24, DS-26, 
D5-28, D5-29 

integer editing, 
D5-11 to 13, 
D5-16, DS~17, 
D5-24, D5-26, 
D5-28, D5-29 

pattern editing, D5-8 
to 10, D$-19 to 
23 

relative tabbing, 
D5-11, DS-12, 
D$-18 

T, D5-10, DS-11, D5-13 

text insertion, D5-12 
to 13, DS-13, 
D$5-19 to 22 

X, DS-11, DS-12, D5-16 

Format string 
construction, D5-« 
definition, D5-3 
processing, D5-^ 


D5-6, 
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Format zeros as text, 
D$-20, D5-25, D5-27 
Formatting of disks, 
A3-3, A3-9, BS-1 
Formatting of output, 
C86 to 91, C102 
advanced techniques, 
DD-1 to 12 
aids to, D6-1 to 9 
default, Fi-35 
default conventions, 
D2-1 
multiple-line, 
12 
special considerations, 
DE-1 
summary, DF-1 
variable-length, 
DD-10 
E4-1, G3-94 to 


D10 to 


DD-9, 


OFRDAC, 
85 
DFRDCI , 
97 
FREAD, 
ag 
OFRENAME, 2-5, 22-6, 
G3-100 to 102 
ÜFREPLACE, E2-1, E2-2, 
63-103 to 105 
DFRESIZE. E2-5. G3-106 
to 108 
DFSIZE. E2-3. G3-109 to 
110 
Destac, 
112 
JFSTIE, 
UFTIE, 


E3-4, G3-96 to 


Ei-8, G3-98 to 


Ea-1, G3-111 to 


63-113 to 115 
E1-7, G3-116 to 
118 
Full-screen editor, 
B3-1, B3-S to 6, 
F2-12, F3-7 to 18 
actions in, F3-9 to 15 
activating, F3-8 


changes made, G3-238 

column number 
displayed, 
G3-237 

error reports in, 
F3-17 to 18 

exit method, G3-238 


line numbers on/off, 
G3-252.1 

margins, G3-238 to 239 

programming with, 
F3-15 

session pending, 
G3-239 
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truncated lines in, 
F3-14 
units in, F3-8 to 9 
vs. function definition 
mode, F3-7 
window height, G3-239 
with JPOKE and SPEEK, 
F3-16 
Function 
ambivalent, 
F1-41 
call, F1-43 
canonical 
representation 
of, see CCR 
copying, G3-29 
debugging with OSTOP, 
G3-261 
definition by APL 
statement, 
G3-43, G3-120 
deleting lines in, 


F1-6, 


F3-4 
dyadic, Fi-6, Fi-41 
editing, see Function 


definition mode 
and Fuli-screen 
editor 
erasing, G3-62 
header, C6-3, F1-40 to 
al, F3-2 
lines of a, F1-42.1 
list of, in workspace, 
F2-16, G3-166 
local, G3-43 
locking, G3-192 
matrix representation, 
see DCR 
Fi-13 
Fi-6, Fi-41 
Fi-6, F1-41 
Fi-46, F2-34 
defined, 
FI-43 
primitive non-scalar, 
Fi-13 
primitive scalar, 
recursive, defined, 
Fi-43 
restartable, Fi-47 
scalar dyadic, F1-7 
suspended, F2-34 
suspended. defined, 
F1-43 
syntax. C77 
tracing execution, 
63-277 


mixed, 
monadic, 
niladic, 
pendent, 
penden: 


F1-7 
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user-defined, structure 
of, Fi-40 
vector representation, 
see LVR 
Function call, see 
Function, call 
Function definition mode, 
B3-2 to 3, C63 to 
76, P3-1 to 6 
deleting lines in, 
F3-4 
displaying lines in, 
F3-3 
entering, F3-1 
error reports in, 
leaving, F3-2 
prompts in, F3-3 
vs. full-screen editor, 
F3-7 
Function header, see 
Function, header 
Punction keys, see 
Programmed function 
keys 
Function line 
changing under program 
control, see 
GDEFL 
reading under program 
control, see 
Ger. 
DFUNTIE, Ei-7?, F1-7, 
G3-119 


F3-6 


Fuzz 
system, Fi-5 
ÜFX. 63-120 to 121 
vs. JDEF, G3-45 
€ format phrase, D5-8 to 
10, D5-19 to 23 
Game control adapter, 
63-18 
Gamma function, F1-10 
Garbage collection 
effect on DSTP7R, 


G3-265 
forced at keyboard 
unlock G3-239 


DGCIRCLE, B9-3, B9-1, 
G3-122 to 125 
ge. Fi-i11 
ÜGINIT, B9-5, G3-126 to 
132.1 
initializing graphics 
memory, 39-3 
OGLINE, B9-3 to 5, 
G3-133 to 136 
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Global environment, 
P1-42 

[IGMASK, BS-3, B9-5, 
63-137 to 138 

goto, Fi-45 to 46 

DGPAINT, B9-4, B9-5, 
63-139 to 142 

OGPRINT, B9-3, G3-143 to 
184 


Changing orientation, 
G3-239 
header/footer strings, 
G3-240 
Grade functions, F1-22 
details on, F1-58 
dyadic, F1-60 
monadic, F1-S9 
Graphics 
adapter, see Adapter 
arc. see DGCIRCLE 
aspect, G3-152, see 
also [IGCIRCLE 
Cartesian coordinates 
and, G3-154 
character display. 
B9-« to 5, see 
also (¢WRITE 
character generator, 
B9-* to 5, G3-240 
circle, see TGCIRCLE 
display environment, 
Bs-2 


distortion, G3-152, 
see also ¢WINDOW 
dithering, see 
Dithering 
(graphic) 
ellipse, see [GCIRCLE 
fill an area, see 
DGPAINT and 


DGSEADE 
function syntax of, 
B9-5 
hardware 
considerations, 
B3-1 
initialize, display. 
see DGINIT 
line, see DGLINE 
magnify image, see 
DGWINDOV 


magnify text and 
pattern, see 
dez00M 

mask pattern, see 
JGMASK 

origin, G3-154 

overview of, B9-1 to 5 
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palette, 63-126 
pie-shaped wedge, see 
JeCIRCLE 
pixel interaction, see 
ÜerYPE 
points, see DGLINE 
printing, BS-3, B9-5, 
see also IGPRINT 
projection, see DGYIEW 
rectangular bars, see 
DGLINE 
reserving memory for 
printer, B1-6, 
B9-3 
shade rectangular 
areas, see 
DGSBADE 
state-setting 
functions, 
89-3 
status, see [ESTATUS 
straight lines, see 
22471 
see Graphics, 
character display 
uneven scaling, BS-2 
viewport, see DGVIEW 
wedge, see GCIRCLE 
with QPOKE, 63-239 to 
240 
Greater than, C49, Fi-11 
Greater than or equal to, 
Fi-11 
Grouping symbols 
for formatting, 
D5-17 
DGSHADE, 3B9-4, B9-5, 
G3-145 to 147 
JeSTATUS. G3-148 
Oeryrr, B9-5, G3-149 to 


89-2, 


text, 


DS5-16, 


150 
UGYIEW, B9-2, B9-3, 
B9-5, G3-151 to 152 
ÜGMINDOV, B9-2, BS9-3, 
B9-5, G3-153 to 155 
TEWRITE, B9-1, B9-3 to 
5, G3-156 to 157 
D6200M, B9-3, 
B9-5,G3-158 to 159 


R= APL startup option, 
B1-6 

Handles, see File, 
handles and 


INSUFFICIENT 
BANDLES 
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Hard disk, see Disk 
drive, hard 

Hardware environment, 
Bi1-1, B1-5 to 7 

non-IBM, 81-8 to 11 

Hayes, F5-13, G3-11 

)HELP, B3-7, Ba-1, F2-17 
to 18, F4-1 

DEELP. B3-?, B4-1, F4a-1, 

G3-160 to 161 


HELP facility, B1, B3-1, 
B3-6 to 7, B4-1 to 
3. F2-17 
activating, see )HELP 
and L 
changing screen width, 
G3-240 
default topic, see 
Qaroric 
files in use, see 
DENAMES. 


guiding with DETOPIC, 
Pu- 


no error handling in, 
FR-6 
ÜPOKE locations in, 
G3-233 
user actions in, B4-2 
HELP file 
building, Fa-1 
current, see [JENAMES 
directory design, F4~-8 
not found, F2-17 
structure of, F4-2 
Help key, 32-13, B4-1, 
Bà-3 
in full-screen editor, 
F3-10 
in numeric editor, 
F3-26 
Help Line (phone), 
B10-3, see also 
STSC, Inc., 
contacting 
HelpEnd, B2-i4, B4-3 
Hercules, see Adapter 
High intensity attribute, 
see Attribute, 
video 
Highest number, F1-31 
Highlight attribute, 
selecting, G3-238 
OENAMES, B4~1, F2-18, 
F! G3-162 to 163 
1 


Hold, B: 
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Home, B2-7 
in terminal mode, B?-4 
with Alt, B2-8.1 
with Ctrl, B2-7 
Horizontal tab stops, 
F5-13 
HT (ASCII), 
FB-4 
DETOPIC, Bu-1, F*-1. 
G3-164 to 165 
Hydrant, F1-27 


B?-3, FS-13, 


I format phrase, D5-6, 
DS-11 to 13, D5-16, 
D5-17, D5-24, 
D5-26, D5-28, D5-29 

I= APL startup option, 
Bi-6, G3-182 

IBM enhanced graphics 
adapter, see 
Adapter, IBM 
enhanced graphics 

IBM graphics adapter. 
see Adapter, IBM 
color 

IBM graphics printer, 
G3-131 to 132 

Identifier, Fi-2 

classification, see 
DIPLOC and ONC 
list, see [,DLIS? and 

ONL 

local, Fi-40, Fi-42 

shadowed, F1-42 
space used, see [SIZE 

Identity, F1-8.1 

ÜIDLIST, F2-16, F2-38. 
63-166 to 167 


vs. ONL, G3-187 
DIDLOC, F1-50, G3-168 to 
ies 
vs. DNC, G3-169 


IERE floating-point, see 
R 


Immediate execution mode, 
B3-1 to 2, Ci2 
prevented by DS4, 


63-250 
Implicit output, F1-34, 
F1-38 
vs., explicit result, 
Fi-6 


DIN. G3-170 to 173 
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DINBUF. G3-173 to 173.1 


with LARBIN, G3-173 
with DEDIT, F3-16 to 
$T 
with (WIN, G3-173.! 
Inclusive or, F1-12 


GINCON function, G3-283 
INDEX ERROR, C38 
Index generator, 
Index of, F1-20 
Index origin, see [IO 
Indexed assignment, 
F1-26 
Indexed by, C35, F1-21 
INIO, see Initial 
workspace 
Initial workspace, 
Bi-3, F5-1 
[IINKEY, B3-1, G3-174 to 
175 
datatype, G3~241 
use in graphics, 
63-132.1 
wait for keystroke, 
63-241 
inline, F1-33 
inner, F1-29 
Inner product, 


F1-2i 


Bi-3, 


BS-1, 


Fi-29 


Inport with LARBIN, G3-6 
to 12 

input, F1-32 

Input, F1-32 


Character, see 
Character input 
Check for, without 
waiting, G3-175 
evaluated, see 
Evaluated input 
modes, B3-1 to 7 
on same line as prompt, 
F1-36 
source file, B1-6, 
G3-170, G3-181 
state, see []IOSTATE 
Insert/replace data on 
screen 
by keystroke, B2-7 
by ŪPOKE, G3-237, 
G3-2u1 
Inserting 
à blank line, B2-8 
characters on the 
screen, B2-7 
INSUFFICIENT HANDLES, 
EC-1 to 2, F2-8, 
63-31 
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DINT, G3-176 to 178 
aná scrolling 
attributes, B2-9 
return from graphics 


display, B9-1 
INT S0hex, G3-6 
Integer data size limits, 
D2-4 
Integer editing, Du-4, 


D5-6, D5-11 to 13, 
D5-16, D5-17, 
DS-24, DS-26, 
D5-28, D5-29 
Integer format, D2-5 


Integrity of data, F$5-1u 
Interrupt 
strong, see Strong 
interrupt 
weak, see Weak 
interrupt 
Interrupt handler 
invoke DOS, G3-176 
user-defined, G3-176 


Invalid data in APLLIBS 
File, B1-7 
Invalid parameter, B1-7 
invert, F1-24, F1-55 

YO, G3-179 to 180 


UIOSTATE, G3-181 to 182 
is, F1-26 

Join, F1-16 to 17 
Joystick, G3-18 


K modifier, 
D5-32 
K= APL startup option, 
B1-6, B6-3 
identifying with [PEEK, 
G3-241 
Key clicks, 3-241 
Key labels, adhesive, 
B2-1 
installing, 
why instali, 
B2-1 
B2-2, B2-3, B6-3, 
B7-2 
in terminal mode, 
87-3, B7-8 
Keyboard 
actions during 
processing, 
52-10 to 13 
layout, 82-1 


D5-18 to 19, 


Ai-i to 2 
Al-1, 


Xeyb. 
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locking with []POKE, 
63-241 
overstrike table 
location, 63-242 
select with [POXE, 
G3-241 to 242, 
see also (KEY 
state testing, B2-6 
states, B2-3 to 4, 
B6-3, B7-2 
test vith [PEEK, 
G3-242 
translation table 
location, 
G3-242.5 
unified, see Unified 
keyboard 
Keystrokes,  F5-17, 
G3-228 
B6-3, F2-19, 
G3-183 to 184 
)KEYWORD,  B6-3, F2-19 
Keyword form, B6-1 to 
11, F2-19 
and ambiguous symbols, 
B6-8 
changing between APL 
symbol form and, 
B6-4, F2-19, 
G3-183, G3-242 
effects of activating, 
B6-5 to 5 
example of function 
display. B6-5 
symbol substitutions 
used, B6-6, B6-7 
symbols available in, 
B6-7 
used to enter 
upper-/lowercase, 
B6-7 
Keyword marker 
default character, 


DKEYW, 


B5-6, Gi-1 

explained, B6-6 

replacing, G3-242.1 

Keywords, B6-1 to 11 

defined, B6-1 

disabling display of. 
G3-242.1 

entering, B6-6 

list of, Bé-9 

list of Alt-assisted 
keywords, B6-10 


list of symbol 
substitutions, 
B6-7 
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mixing with APL 
symbols, 
negative left 
decoration, 
G3-242.1 
origins of, B6-2 
retaining the map 
display, B6-5, 
B6-6 
uses of, B6-1 
KwHelp, B2-13, B6-4, 
B6-5 


B5-3 


L modifier, D5-19, D5-27 
L: APL startup option, 
B1-6 

C125 to 126, 
F1-39 to 40, F1-42 
to 44, Fi-46, F2-7 
identifying, see 

JIDLIST and DNL 


Label, 


Laminate, Fi-17 
Last, B2-14 

in HELP facility, B4-2 
Latent expression, Bi-3, 


F2-24, see also 
DALX, DELY, and SLY 


avoiding, F2-41, 
G3-300 

local, F2-24, F2-41 

Le, G3-185 

le, Fi-il 


Least squares fit, 
Fi-24, F1-55 


Left, B2-6 
in terminal mode, B7-3 
with Alt, B2-8.1 
with Ctrl, B2-6 
Left-justify field 
modifier, D5-17, 
D5-27 
Left-justify titles, 
D6-3 
Length 
maximum, F1-2 
LENGTH ERROR, C13, C20, 
[m 
Less than, C49, F1-11 
Less than or equal to, 
Fi-11 
LF (ASCII), 87-3, see 
also CTCLF 


DL18, £1-9, G3-186 to 
187 


)LIB. 
vs. OLIB, 


Ei-9, F2-20 
G3-186 
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Library, E6-1 to 4 
as DOS directory, 
F2-22, see also 


DLIBSS 
default, FS-8 
defined, B1-2, E1-2 


list APL files in, see 
)FLIB and DFLIB 

list contents of (all 
files in), see 
)LIB and [LIB 

list workspaces in, 
F2-40 

maximum number of, 
5-3 

used with native files, 
E6-4, G3-200 


LIBRARY NOT FOUND, E6-4, 
F2-25 
Library number, E1-4 


DLIBS. E6-2, G3-188 to 
189 
)LIBS. E6-2, F2-22 
LIFO file organization, 
E2-3 to 4 
LIMIT ERROR 
with &, 
Limits 
various system, 
Line 
-drawing characters, 
Bil-1, FA-5 to 6, 
G3-14 
fitting with B, F1-57 
graphic, see DGCLINE 
*Line, B2-8, 82-13 
in full-screen editor, 
F3-12 
-Line, B2-8.1, B2-13 
in full-screen editor, 
F3-12 
Line counter, 
Line number, 
F1-42 
Line numbering in 
full-screen editor 
on/off, P3-11 
on/off with DPOKE, 
G3-242.1 
Linear equations 
solving with &, 
Linefeed character 
for parallel printer, 
Bi-6, B8-4, 
G3-242.1 
suppressing, Bi-$, 
B8-8, G3-242.1 
63-274 


F1-58 


FE-1 


see (LC 
F1-40, 


F1-56 


DTCLP, 
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Listing 
file names, E1-8, 
63-87, G3-92, 
G3-186 
LJUST function, 
D6-3 
ln, Fi1-10 
)LOAD, F2-24 
DLOAD, G3-190 to 191 
Load without executing 
latent expression, 
see )XLO4D and 
DXLOAD 
Local environment, 
F2-16 
Local variable, see 
Variable, local 


D6-1, 


gp2-T, 


DLOCK, 86-7, F5-15 to 
16, 63-192 to 193 
log, Fi-10 
Logarithm 
any base, F1-10 
base e, Fi1-10 
Loop, C123 to 127, Fi-4, 
F5-2 
defined, F1-46 
endless, C127 
Lowercase, B6-6, Fi-2 


Lowest number, F1-31 
LPT1, Bi-S, B8-5, G3-5, 
G3-242.3 


(ky, Bi-3, F2-24, F5-1, 
G3-194 to 195 
avoiding, F2-#1, 
G3-300 
M 
modifier, D5-19 to 20, 
D5-21, D5-27 to 
29 
sample matrix, F1-13, 
F1-28 
M- APL startup option, 
31-6 


Machine language 
interface, see 


[12774 
Magnitude, Fi-9 
Match, F1-22 
Matrix, C18 to 21, F1-3 
display of, D2-6 to 8 
empty, F1-35 
selecting data from, 
C53 to 55 
Matrix divide, F1-24 


F1-28 
P1-55 


Matrix inverse, 
details on, 
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Matrix multiplication, 
F1-29 
Maximum 
function, C31 to 33, 
member, F1-21 
Membership, F1-21 
Memory 
changing contents of, 
see (PORE 
reading contents of, 
see [PEEK 
reserved for APL, 
segment, see [DSEG 
top of, B1-6 
Menu 
choosing a, F4-3 
defined, Fa-2 
design of a, 
structure of, 
using a, F4-3 
Merging files, 
min, F1-9 
Minimum 
function, 
F1-9 
requirements for 
APL*PLUS/PC 
System, Bi-1 
Minus signs, D5-19, 
D5-20, D5-25, 
D5-27, D5-29 
MKDIR (DOS command), 
E6-3 


B1-6 


Fa-6 
Pu-2 


E1-9 


C32 to 34, 


MODE 
DOS command, B3-5, 
B7-1, B8-2, FC-3 
Modem, F5-13 
Modifiers with DFMT, 
DS-17 to 25 
B, D5-17, D5-26, 
D5-28, D5-28 
background fill, 
D5-22, DS-23, 
D5-28 to 30 
D5-17, D5-26, 
D5-28, D5-28 
C, D5-18, D5-29 
combinations of, 
to 28 
comma, D5-18, DS-29 
format zeros as text, 
D5-20, D5-25, 
D5-27 
K, DS-18, D5-19, D5-32 
L, DS-18, DS-27 
left justify, D5-18, 
D5-27 


blank, 


D5-26 
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M, D5-19, D5-20, 
D5-21, D5-27 to 
29 
N, DS5-20, D5-21, 
D5-28, D5-29 
negative left 
decoration, 
D5-19, D5-20, 
D5-21, D5-27 to 
28, G3-282.1 
negative right 
decoration, 
D5-20, D5-21, 
D5-27 to 28 
0, D5-20, DS-26 to 28 
P, DS-21, D5-26 to 28 
positive left 
decoration, 
D5-21, DS-26 to 
28 
positive right 
decoration, 
D5-21, D5-27 to 
28 
Q. D5-21, D5-26 to 31 
R, D5-22, D5-23, D5-28 
to 30 
S, D5-23 to 25, D5-32 
scaling, D5-18, DS-19, 
D5-32 
symbol substitution, 
D5-23 to 25, 
D5-32 
Z, DS-25, D5-26, D5-2? 
zero fill, D5-25, 
D5-26, D5-27 
Modulo, Fi-10 
Monadic 
defined, C21, F1-6, 
Firat 
Monitor 
color mode setting, 
G3-240 
display, see Adapter 
display memory 
location, 
G3-242.4 
key, enable/disable. 
G3~242.2 
switching between, 
B2-13 to 14, 
G3-242.2 
Monochrome adapter 
Hercules, A2-4, G3-127 
IBM, A2-1, G3-129 
Monochrome attributes, 
G3-287 


More, B2-11 
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Multiple-line formatting, 
DD10 to 12 
Multiplication 
arithmetic, F1-9 
logical, F1-12 
matrix, F1-29 


N modifier, D5-20, 
D5-21, DS-28, D5-29 
Name 
classification, see 
DIDLOC and INC 
for data, Fi-i 
for variable, Fi-1 
function, Fi-2 
list, by 
classification, 
see [IDLIST and 
ONL 
of a workspace, F2-39 
of tied files, E2-1, 
G3-92 
variable, maximum 
length of, Fi-2 
Naming conventions 
for files, E7-5 
nand, F1-12 
UNAPPEND, Ei-6, G3-196 
to 197 
Native file 
accessing through 
libraries, E6-4, 
63-200 
add data, see “WAPPEND 
and OWUNTIE 
allocate space for, 
see LNRESIZE 
Create, see INCREATE 
damaging, E7-4 
defined, E1-1 
erase, see [NERASE 
example of using, B-1 
to 2 
read data from, see 
(wREaD 
replacement of data, 
E7-2 to 3, see 
also DWREPLACE 
and [NUNTIE 
tie, see CATIE 
tied, see ^NNAMES and 
DNNUMS 
updating, £7-3, see 
also DNUNTIE 
vs. APL files, E1-10, 
E?-1 to 5 
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ONC, G3-198 to 199 
vs. DIDLOC. G3-169 
ONCREATE,  Ei-5, G3-200 
to 202 
ne, F1-12 
NEDIT, see Numeric editor 
Negation 
logical, F1-12 
Negative left decoration 
modifier, D5-19 to 
20, D5-21, D5-26, 
DS-27, G3-242.1 
Negative number, C13 to 
14 
Negative right decoration 
modifier, D5-20, 
DS-21, D5-26, D5-27 
ONERASE, 1-9, G3-203 to 
208 


Newline character, see 
ÜTCNL 
Newsletter, B11-2 
Niladic 
defined, Fi-6, Fi-41 
INL, F2-16, F2-38, 
G3-205 to 206 
ONNAMES, E2-1, G3-207 
ÜNNUMS, 2-1, G3-208 
NO EDIT SESSION PENDING, 
63-58 
INO SPACE FOR DDM, G3-51 
Non-IBM environments, 
see Hardware 
environment, 
non-IBM 
NONCE ERROR 
JEDIT, F2-12 
QEDIT, G3-58 
nor, Fi-12 
not, Fi-12 
NOT COPIED, F2-7, F2-28 
Not equal, C49, F1-12 
NOT SAVED,  F2-33 
NOT YOUR WS, F2-u2, 
63-301 
INREAD, E1-8, G3-209 to 
210 
ÜNREPLACE, E2-2, G3-211 
to 212 
DNRESIZE. E2-7, G3-213 
to 214 
E2-3, G3-215 
E1-7, G3-216 to 
217 
NUL (ASCII), see ^TCNUL 
Number 
highest, F1-31 
lowest, F1-31 
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Numeric 

data, C28, Fi-2 

data conversion from 
character, see 
OFZ and Execute, 
primitive, 
details on 

data verification, see 


Dvr 
pad, B2-2, 52-3, B2-4, 
63-242.2 
Numeric editor, F3-19 to 
31 
actions in, F3-25 to 
28 


activating, F3-21 

customizing, F3-29 to 
31 

display format of, 
F3-21 

error reports in, 
F3-28 to 29 

modes, F3-22 to 25 

numeric precision, 
F3-20 

syntax of, F3-21 

workspace, F3-21, 
F6-34 

DNUNTIE. E1-7, G3-218 


0 modifier, D5-20, D5-26 
to 28 
0-Over-U-Over-7, B2-8.1, 
F1-32 
)OFF, Bi-4, E1-8, F2-26 
Off-screen scrolling, 
see Scrolling 
screen memory 
Open Me First envelope, 
A1-1 
OPEN QUOTE ERROR, F3-18 
Opening a file, E1-7 
effect on access 
matrix, E5-3 
Operator, Fi-6, F1-28 
or, C51 to 53, Fi-12 
ORCHID. see Adapter, 


ORCHID 
Order 
of evaluation, Ci4 to 
15, F1-38 


of string processing by 
JFMT, DS-4 
DOUT, G3-220 to 223 
outer, F1-29 
Outer product, F1-29 
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Outport with DARBIN, 
G3-6 to 12 
Output, Fi-32, Fi-35 
implicit, F1-34 
insertion or 
replacement, 
Fi-37.1, 63-241 
route to file or 
screen, see [OUT 
sink file, G3-181 
state, see DIOSTATE 
Over, B2-2, B2-8 
Overstrike, B2-8 to 8.1, 
F1-6, FA-2 to 6 
table. location of, 
63-242 
transmission, G3-8 
with [TCBS, G3-242 
Overriding the access 
matrix, E5-3 
overturn, F1-26 
Ownership 
defined, E1-2 


P modifier, D5-21, D5-26 
to 28 
P= APL startup option, 
B1-6 
Pad 
cursor, B2-2 to 4 
key, B2-2 to 4 
numeric, B2-2 to 4 
selecting 
cursor/numeric, 
G3-242.2 
Palette, see Graphics, 
palette 
Parallel printer port, 
see Printer, 
parallel, 
Parameter 
decimal position, 
D$-15 
field width, D5-13 to 
14 
pattern text, D5-14 
position, D$-15 
repetition factor, 
D5-15 
significant digits, 
DS-i4 | 
with OPMT, D5-13 to 15 
Parentheses, C15, C49, 
D5-16, D5-17, F1-38 
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Passnumber, 
to à 
different ones for same 
user, E4-4 to 5 
importance of, E5-2 


Ei-4, Ew-2 


valid values for, E5-2 
Pattern formatting, D5-8 
to 10 
)PCOPY, F2-27 
DPCOPY, G3-22* to 226 
OPEEX, G3-227 
for graphics character 
set, B9-5 
locations for, G3-234 
to 242.6 
Pendent 
defined, F1-43 
OPFKEY, G3-228 to 231 


PF keys, see Programmed 
function keys 
pi, Fi-11 
Pie-shaped wedge, see 
DGCIRCLE 
Plotters, F5-12 
Points (graphics), see 
U6LINE 
B2, Ei-5, F1-37, 
63-232 to 242.6 
locations for, G3-234 
to 242.6 
locations in system 
HELP file, F4-8 
DSEG and, G3-233, 
G3-253 
Poking into memory, see 
Dp: 


DPOKE, 


Polynomial curve 
fitting with E, F1-57 
Polynomial evaluation, 
F1-23 
Port 
communications, 
parallel, G3-5 
RS-232, G3-5 
serial, G3-5 
Position parameter vith 
ÜFMT, D5-15 
Positive left decoration 
modifier, D5-21, 
DS-26 to 28 
Positive right decoration 
modifier, D5-21, 
D5-26 to 31 
Fi-10 
D2-4, D2-5, D5-32, 
G3-243 to 244 


G3-5 


power, 
OPP, 
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Print 
key, B2-12 
precision, see DPP 
width, see DPW 
Printer 
activating system, 

B8- 

APL characters on, 

A2-3. A3-14, B8-3 

to 4 
automatic linefeeds 

with, B8-5, 

G3-242.1 
character set location, 

G3-242.3 
displaying screen 

contents on, 

BB-5 to 6 
formfeed, see DTCFF 
graphics display, 

63-130, G3-140 
on/off under program 

control, 

63-252.3 
parallel, port, 

88-1, G3-5, 

G3-242.3, see 

also LPTi 
selecting system, B8-5 
support for, B8-1 to 6 
system, see System 

printer 
translations for, 

A3-14, B8-3, 

G3-6, G3-242.5 

Printing precision, 
D2-^, G3-243 
Printing width, D2-1, 
D2-2, G3-245 
Program, C6, C62, see 
also Function 
Program nanes 
CAPTURE, G3-26 
CENTER, D6-1 to 2, 

D6-6 
COLNANES, 
CSSMAT, G3~1 
CSSMATML, G3-21 
INCOR, G3-85, G3-283 
LJUST, D6-1, D6-3 
RELMASS, G3-65 
RJUST, D6-1, Dé-3 
ROWNAMES, D6-1, D6-4 

to 5 
RWTD. D6-1, D6-7 to 8 
SCREENSAVECMD, G3-26 
SHARE, 53-3 


Bi-1, 


D6-1, D6-4 
9 
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SQRT, 
TIME, E3-4 
TIMEN, E3-4 
Programmable 
character set, A2-1 
Programmed function keys, 
B2-1, B2-12 to 13, 
G3-228 to 231, 
G3-242.3 
internal key numbers 
of, Bi-9, 63-228 
with Alt, 82-13 to 14 
with SIM3278, B7-6 
Programmed learning, 
Fant 
prompt, F1-36 
with D4RBIN, G3-5 
Protocol, transmission, 
B7-2, B8-3, G3-7 
Public comment display, 
see FCRLPC 
GPW, D2-1, D2-2, G3-2u5 


G3-65 


Q modifier, D5-22 to 23, 
D5-28 to 30 
Q= APL startup option, 


B1 
DQLOAD, 
247 
Quad, F1-32 
Quiet load a workspace, 
see DLOAD 
Quote 
single for character 
constant, Fi-1 
Quote-quad, F1-33 


6 
F5-1, G3-246 to 


R modifier, D5-22 to 23, 
D5-28 to 30 
R- APL startup option, 


Radians 
and degrees, Fi-11 
Random numbers, see also 
DRL 
with duplicates, F1-12 
without duplicates, 


F1-14 
Rank, F1-2 to 3 
ravel, F1-15 
Readability, F5-8 


Reading from a file, 
E1-8, G3-88, 63-209 

Recall previous line, 
B2-14 to 15, F2-2 

reciprocal, F1-8 
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Rectangular bars, see 
DGLINE and DGSEADE 
Recusive, F1-43 
Reduction, C32 to 34, 
C52, Fi-31, F1-53 
Registers, CPU, G3-176 


Relative tabbing, DS-11, 
D5-12, DS-16 
RELMASS function, G3-65 


Removing file components, 
E2-2 
RENAME (DOS command), 
E2-6 
Renaning a file, 
63-100 
Repetition factor vith 
JPNT, D5-15 
Replace/insert data on 
screen, 63-237 
Replacing data in a file, 
E2-1, 63-103, 
63-211 
Replicate, F1-19 
Report formatting with 
DENT 
column names, 
D6-4 
custom titling, 


E2-5, 


D6-3, 
D6-7 


to 8 
examples, Di-4, D6-6 


to 7 

formatting aids, D6-1 
to 9 

row names, D6-5 to 6 


setting up format of, 
D1-3 to 4 

titles, D6-1 to 3 
Reporting system bugs, 
B10-2 to 4 
represent, F1-24 

Representation, 
Requested output 
with following newline, 


Fi-24 


F1-35 
with no following 
newline, Fi1-36 
)RESET,  F2-30 


Resetting the default 
environment option, 
B1-11 

reshape, C19, Fi-i¥ 

residue, F1-10 

Restricting access to 
files, B4-2 to 4 


F1-6 


reverse, Fi-26 
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Reverse video, see 
Attribute, video 
Right, B2-6 
in terminal mode, 
with Alt, B2-8.1 
with Ctrl, B2-6 
Right-justify titles, 
D6-3 
Right-to-left, 
F1-38 


87-3 


Cis to 


rise, 
RJUST function, D&-1, 
D6-3 

G3-248 to 249 
C39 to 40, F1-12 
E6-1 


IRL, 
roll, 
Root directory, 


ROM, see Character ROM 
rotate, F1-18 
Rounding, DC-1 to 2 
error, G3-48 
Row names, D6-4, D6-5 
ROWNAMES function, D6-1, 
Dé- to 5 
RS~232 port, Bi-1, Bi-5, 
B3-5, B7-1, F5-12 
to 13, G3-5 
for serial printer. 
B8-1 to 3 
using BIOS for, B1-10 
to 11 
RTS-CTS protocol, B8-3, 
G3-7 
RWTD function, D6-1, 
D6-7 to 8 
s 
modifier, D5-23 to 25, 
D5-32 
sample scalar, F1-13, 
F1-28 
S= APL startup option, 
B1-7 
DSA, F2-4, F2-26, G3-250 
to 252 
)SAVE, F2-31, F5-10 
Scalar, F1-3 to 4 
display of, D2-6 
Scaling modifier, DS-18, 


D5-19, D5-32 
Scan, F1-30 
defined, C35, F1-53 
details on, F1-52 
identities with 


Booleans, F1-S4 
implementation, F1-54 
SCION, see Adapter, 
SCION 
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Screen, see also Window 
active window, see 
OWINDOW 

attributes, see 
Attribute, video 
attributes and 
scrolling memory, 
B1-S, B2-8.2, 
G3-5. G3-36, 
63-177 
clearing, see [TCFF 
columns on, see [CRT 
lines on, see [CRT 
special output to, 
63-13. see also 
DARBOUT and DWPUT 
SCREENSAVECMD function, 
63-26 
Scrollt, B2-8.2, B2-9, 
F3-13 
Scrolls, B2-8.2, B2-9, 
F3-13 
Scrolling screen memory, 
B2-8.2 to 10, see 
also [CRT 
buffer size, 
clear, G3-177 
protect/release, 
G3-242.3 
retaining video 
attributes, 
B1-$, G3-177 
Seconds since session 


Bi-? 


startup, see DAI 
Security of data, F5-15 
to 16 
DOSEG, G3-253 to 254 
with CPEEK and “POKE, 
63-233 
Semicolon 
in function header, 
F1-42 
in subscripts, F1-21, 
F1-26 
with CFMT, D5-2, G3-89 
Separate column 
formatting, D5-30 
Serial port, G3-5 
Session 
APL, ending an, Bi-4, 


F2-26, 63-177, 
63-250 

APL, self-starting, 
F5-1 

APL, starting an, 
A3-13 

DOS, self-starting, 
F5-1 
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DOS, ending a, -B1-^ 
user-defined startup 
values, G3-242.4 
Shade graphics area. see 
DGPAINT and [¢SHADE 
Shadowed name, Fi-42 
shape, C17, C19, F1-14, 


F1-42 
SHARE program, E3-3 
Shift. B2-2, B2-3 


)SI, F1-43, F2-34, F5-11 
OSI, F1i-43, G3-255 
)SIC, F1-46, F2-35, 
FS-11 
Sign 
Changing, 
sign 
of a number, Fi-8.1 
Significant digits, D2-5 
to 6, G3-243 
parameter with FMT, 
DS-14 
Signum, F1-8.1 
S1M3278, see Terminal 
mode, using S1M3278 
Sine, Fi-11 
Single-character input, 
see []INKEY 
P1-43, F2-36 
DUSINL, F1-43, G3-256 
[SIZE, Fi-2, G3-257 
Size limitations 
of files, E1-2 


F1-8.1 


)SINL, 


Size of a file, E2-3. 
E2-6 
Slippery tie, G3-114, 


G3-116, G3-209, 


G3-216 
Software environment, 
system, Bi-i, B1-5 


to 6, see also DOS 
solve, Fi-24, F1-55 
Sorting, F1-22 
details on, F1-58 
ÜSOUND, B1-10, G3-258 to 
259 


Space 
disk, recovering, F5-9 
key (space bar), B2-3 
reservation on disk, 
E7-2 
used by data, Fi-4, 
see also [SIZE 
Speaker, built-in, Bi-1 
and chirp, see [TCBEL 
and tones, see [SOUND 
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Special formatting 
considerations with 
APL*PLUS/PC, see 


APL*PLUS/PC, 
special formatting 
considerations 

Special keys, list of, 
B2-3 

SQRT function, G3-65 

Oss, G3-260 

STACK FULL, F1-43 


Stars in formatting 
to replace in output, 
DS-24 
in result, D4-7, D$-6, 
DS-i4, D5-32, 
DB-1, DB-2 
Starting an APL session, 
Bi-3 to 8 
example of, B1-7 
options when, Bi-4 to 
8 


Startup options 
(parameters), Bi-4 


to 8 

State indicator, C66, 
F1-43, F1-"5, 
F2-30, F2-34 to 36 


clearing the, F2-35 

displayed, see )SI, 
ÜSI, )SINL, and 
ISINL 

2 in, F1-49 

with local names, 
F2-36 


State keys, B2-2, B2-3 

Statement, F1-5 
compound, F1-39, F1-48 
executable, F1-38 
non-executable, F1-39 
restartable, Pi-47 
types of, F1-37 

)STATLINE, B2-S, F2-36.1 

Status line, see System 

status line 


DSTOP, Fi-53, F2-7, 
F2-27, G3-261 to 
263 

Stop action, see []$4 

Storage 


of datatypes, F1-4 
used by file, E2-3 
JSTPTR. G3-264 to 265 
with JCALL, G3-17 
Straight lines, see 
OGLINE 
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String 
processing by DFMT, 
Ds-4 


search, see JSS 
Strong interrupt 
defined, B2-10 
effect on DIN, G3-171 
effect on (OUT, 63-223 
STSC, Inc, 
contacting, A2-2, 
B10-3 
newsletter, B11-2 
Subdirectory, E6-1 to 4 
Subscript, F1-21 
subtract, Fi-8.1 
Support policy on 
APL*PLUS/PC System, 
B10-1 to ^ 
Suspended 
defined, C66, Fi-43 
USYMB, G3-267 
Symbol form, see APL 
symbol form 
Symbol substitution with 
ÜFMT, DS-23 to 25, 
D5-32 
Symbol table, F2-37, 
G3-224 
pointer, see [STPrR 
SYMBOL TABLE FULL, F2-8 
)SYMBOLS,  F2-37 
Symbols, number in 
workspace, see 
Osyme 
Syntax, F1-5 
Conventions, E2, Gi 
SYNTAX ERROR, C14, F1-5 
SYSHELP file, Ba-1, 
Fa-8, G3-162 
QSY$1D. G3-268 
System clock, see Clock, 


system 
System command, C96 to 
103, F2-1 
vs. system function, 
F2-1 


System constant. G1-5 
System disk 
unneeded after APL 
starts, A3-13 
System formatting 
(default), D2-1 to 
3 
System function 
alphabetical list of, 
61-1 
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characteristics of, 
E1-3, G1-2 
defined, C102 
grouped by purpose, 
G2-1 to 2 
vs. system command, 
F2-1 
System input modes, see 
Input, modes 
System printer 
activating, G3-242.3, 
see also Print 
selecting port for, 
Bi-7, G3-242.3 
selecting translation 


for, B1-7, 
G3-242.5 

System reset, B1-3, 
B2-12 


System status line, B2-4 
to 6, F2-36.1 
System variable 
alphabetical list of, 
61-1 
grouped by purpose. 
62-1 to 2 
local, Fi-42 
session-related, G1-4 
VS. system command, 
F2-1 
workspace-related. 
F2-4, G1-3 
format phrase 
to 11, D5-13 
T= APL startup option. 
B1-7 
Tab, 2-7 
in terminal mode, B7-3 
Tab stops, F5-13 
Tabbing with JPNT 
absolute, D5-10 to 11, 
DS-13 
relative, D5-11 


3 


D5-10 


Table, F1-3 

Tagged block, F3-9, 
F3-11, F3-22, F3-27 

take, C122 to 123, Fi-15 

Tangent, Fi-11 

Ore, G3-269 

DTCBEL, G3-269.1 

DTCBS, G3-270 

ITCDEL, G3-271 

DTCESC, B7-4, B7-6, 
G3-272 

Orcrr, G3-273 
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ÜTCLF, B8-4, G3-11, 
63-274 

B8-4, F1-35, 
F1-36, G3-9, G3-275 
DTCNUL. G3-276 
TECMAR, see Adapter, 


Term., B2-14, B?-1 
Terminal, intelligent, 
G3-9, G3-11 

Terminal key values, 
G3-242.5 
Terminal mode, B3~1, 
B3-5, B7-1 to 10 
character sets, B7-2 
customizing, 87-9, 
G3-242.5 
entering, B7-1, 
G3-242.5 
exiting, B?-1 
general discussion of, 
B3- 
keyboard switching, 
G3-242.5 
local features, B7-5 
reception features, 
B7-S to 7 
scrolling in, B7-5 
transmission features, 
B7-3 to 5, 
G3-282.5 
using SIM3278, B?-8 to 
E 


Text deletion, see 
Deleting, 
characters 

Text with []FMT 

Gelimiters, D5-3 

insertion, Ds-11 to 
13, D5-13, D5-19 
to 22 

Text insertion, see 
Inserting, 
characters 

Text keyboard,  B2-3 to 
4, B7-2, G3-241, 
G3-242 

Thorn, Fi-25 

Tie number, C107, C110 
to 111, Ei-u 

negative for native 
files, E1-10 

of tied files, E2-1, 
63-93, 63-208 


TIME 
DOS, FC-1, FC-3 
for APL timestamps, 

E3-4 
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Time, elapsed, see 
Clock, system 
TIMEN function for 
timestamps, 
times, F1-9 
Timestamp, see DTS 
Titles, DD-6 to 7 
centering, D6-2 
custom routines for, 
Dé-6 to 8 
left justifying, 
right justifying, 
Too many paths, B1-7 
Topic for HELP, see 
DETOPIC 
OPRace, F2-7, F2-27, 
63-277 to 279, see 
also DLOCK 
Trace function execution, 
see [TRACE 
Translations for printer, 
see Printer, 
translations for 
Transmission 
codes, FB-1 
of data, see 
Communications 
protocol, see 
Protocol, 
transmission 
transpose, F1-20 
trig, Fi-i1 
Truncated lines, F3-14 
not using BREAK or Exit 


53-4 


D&-3 
D6-3 


with, F3-15 
Ors, 63-280 
.TSF, F2-20, G3-78 
.TWS, P2-20, F2-31 


Tying a file, E1-7 
effect on access 
matrix, E5-3 
Type-ahead buffer, F5-17 
to 18, 63-173 to 
174 
H= APL startup option, 
B1-6 


Typewriter-pairing, FB-2 


DUE, G3-281 
Underlining 
numbers, DD-7 to 9 
Screen attribute, see 
Attribute, video 
Underscores in formatted 
output, D4-8, 
D5-32. DB-1, DB-2 
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Unified keyboard 
APL startup option, 


B1-6 
testing for, G3-241 
using, B2-3 to 4 


Untrappable error, see 
also Error 


effect on DIN, G3-173 
effect on Gov7, G3-223 
Untying a file, E1-7, 


Ei1-10, G3-119, 
G3-218 
Untype, B2-8.1 
in terminal mode, 
B7-3, G3-242.5 
Unwrap, B2-13 
Updating a file, E2-2, 
E7-2 to 3, G3-103, 
G3-211 
upgrade, Fi-22 
details on, 
User 
defined, E1-2 
User account number, 
B1-3, E1-2, E3-2 
distinct, B1-4 
valid range of, Bi1-u 
User responsibilities, 
B5-1 to 2 


F1-58 


Y, Fi1-13, F1-28 
VALUE ERROR, C65 to 66, 
C75, C130 
Variable 
assigning by [ICALL. 
G3-16 
copying, see )COPY, 
DCOPY, YPCOPY, 
and "]PCOPY 
defined, C9, Fi-i 
editing, see 
Full-screen 
editor and 
Numeric editor 
erasing, see )ERASE, 
ÜERASE, and GEX 
global, C128 to 130, 
F1-40 to 41 
list of, in workspace, 
F2-38 
C128 to 130, , 
F1-40 to 41 
maximum size of, F1-2 
name list, see )VARS, 
DIDLIST, and QNL 


local, 
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Variable-length 


formatting, DD-9 
to 10 
)VARS, F2-38 
Vector, C13, Fi-3 
character, defined, 
C30 
display of, D2-6 
empty, Fi-3 


representation of 
function, see 


DPR 
verify numeric format, 
see VI 
CFI, F1-48, G3-282 to 
283 
avr, G3-284 


W= APL startup option, 
Bi-? 
DWA, Fi-5S. G3-285 
WANG, Bi1-5 
Weak interrupt 
defined, B2-10 
trapped, see  ALX 
Wedge. pie-shaped 
(graphics), see 


ÜGCIRCLE 
OWEET, G3-285 to 288.1 
where, F1-20 
OWIN, G3-288.2 to 288.6 


[WINDOW, G3-291 to 293 
Window, graphics, see 


IGWINDOW 
Window, screen 
active, see [WINDOW 
Clearing, see C7CFF 
reading from, see 
ÜwcET 
writing to, see WPUT 
Without, Fi1-18.1 


DWXEY, G3-290 to 290.3 
Word processors, El 
Working copy 


creating a, A3-4, A3-9 
Workspace 
active, C96, F2-24, 


F2-31, G3-190 

area available, see 
Wa 

chaining, G3-194 

compared with files, 
E1-3 

Copy, see )COPY and 
ICOPY 

defined, C96 


Comprehensive Index 


identification, see 
Workspace 
identification 
initial, FS5-1 
library, see )WSLIB 
and ÜWSLIB 
see )LOAD and 
DLOAD 
load without latent 
expression, see 
)XL04D and OYLOAD 
load without saved 
message. see 
D01049 
owner, see “WSOWNER 
protected copy, see 
)PCOPY and “PCOPY 
saved, F2-10, F2-41 
self-starting, F5-1 
Size, see [WSSIZE 
supplied with 
APL«PLUS/PC 
System, Bi1-1 
timestamp, see WSTS 
too big to save, FS5-10 
Workspace identification, 
Ei-4, F2-31, see 
also )WSID and 
OwsrD 
composition of, 
defined, F2-39 
DWPUT, G3-291 to 293 
Wrap, B2-13 
in terminal mode, 
setting marker, 
G3-242.6 
Wrapped lines, 
WS PULL, F1-43 
defined, F5-3 
detailed discussion, 
P5-2 
with OPMT, DA-2 
with full-screen 
editor, F2-14 
with numeric editor, 
F3-28 
with B. P1-58 
VS NOT COMPATIBLE, 
72-25, G3-191, 
63-247, G3-302 
WS NOT FOUND, F2-25, 
63-191 
WS TOO BIG, 
63-191 
F2-39 
G3-294 
F2-40 


load, 


72-88 


B7-3 


B2-8 


F2-25, 
WSID. 


Owsrp, 
WSLIB, 
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DW$L18, G3-295 to 296 


width for, G3-242.6 
DWSOWNER. G3-297 
QWSSI2ZE, F5-11, G3-298 
OwsTs, G3-298 

x (keyword), F1-9 


X format phrase, 
D5-12, D5-16 

X- APL startup option, 
31-7 


DS-11, 


)XLOAD, F2-41, G3-194 

DXLO4D, G3~-194, G3-300 
to 301 

XON/XOFF protocol, B7-2, 
B8-3, G3-7 


Y= APL startup option, 
B1-7 


Z modifier, D5-25, 
D5-26, D5-27 

Z= APL startup option, 
B1-7 

Zero fill with DFMT, 
D5-25, D5-26, DS-27 

Zeros in formatted 


output, D4-8, DB-1 
zilde, Fi-4 
8087, see 
Floating-point, 
coprocessor 


+ B6-$, C14, see also 
Minus signs 

<, Fi-11 

#. B6-1, B6-5, G1-1 

s, Fi-11 


with functions, 
F3-1 
in output, C87 


B6-6, 


as function, F1-11 
B6-9, F1-9 
F1-12 
Fi-11 
B6-9, F1-44 
F1-12 
F1-12 
F1-12 


> LND vor 


Comprehensive Index 


+. Pi-8.1, Fi-31 
*.X, FP1-29, F1-55 
-, Fi-8.1, Fi-31, see 
also Minus signs 
x 
dyadic, Fi-9, P1-31 
monadic, F1-8.1 
+, B6-9, Fl-11, F1-31 
©, 86-9, C128, F1-39, 
F1-43, F1-44 
as statement separator, 


Pi-4a 
? 
deal, Fi-14 
roll, F1-12 
€, Pi-21 
£, B6-9, B6-10, Fi-20.1 
P. Fi-14 
~, B6-10, F1-12, P1-18.1 
f. F1-15 
*, Fi-15 
1 
dyadic, F1-20 
monadic, F1-21 
©, Fi-11 
*, F1-10 
in Ost, G3-255 


F1-26, F1-35, F1-36 


function, B6-9, F1-19 
operator, B6-9, F1-31 
>, Fi-4, Fi-43, F1-55 to 
46 
) 
function, B6-9, F1-18 
operator, B6-9, C35, 
F1-30, F1-52 to 
55 
from [:, B3-4, F1-33 
niladic, F2-35 
f, Fi-9, F1-31 
L, F1-9, F1-31 
v., B6-9, F3-1 
à. F1-2 
à. Fl1-2 
os Fi-29 
*. Gui 
evaluated input 
primitive, 
F1-32, P1-43, 
F1-45 


indicating keyboard 
input source, 
G3-182 

Start of system feature 
name, G1-1 
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D:. Fi-33 
De, F1-35 
E} 


subscript, 
Pi-38 


F1-21, 


in function definition, 
F3-3 


J+, Fi-26 
+ C15, C49, DS-16 to 
17, F1-38, F5-5 


in system commands, 
F2-1 
the system command, 
B2-14, F2-2 
Bé-4, B6-5, B&-9 
|, B6-9 
i. F1-23, F5-7 
T. Fi-24, F5-7 
Lu 
absolute value, F1-9 
residue, Fi-10 


F1-16 
Fi-15 
P1-17 


dyadic, 
monadic, 
with (.1, 
in function header, 
Fia 
in subscripts, 
P1-26 
with DFMT, 


71-21, 


D5-2, G3-89 
in numbers, 
8s operator, 

1f. Fi-4a 
with compound 

statement, 


Fi-4 
F1-29 


P1-39 
/ 
function, 
operator, 


Fi-19 
Pi-31 


function, F1-18 
operator, C35, F1-30, 
P1-52 to 55 
9, Fi-4 
with DARBOUT, 
v. F1-12 
“e P1-12 
9. F1-40, F3-1, F3-2 
*. F1-23, F1-59 to 62 
À. FP1-22, F1-59 to 62 


F1-37 


Fi-26 
P1-18 


dyadic, 
monadic, 


Comprehensive Index 


&, F1-20 

è, F1-10 

e 

dyadic, F1-26 
monadi P1-18 

z. F1-16 

$ 

function, B6-9, F1-19 
operator, B6-9, F1-31 
* 

function, B6-9, P1-18 
operator, B6-9, C35, 


F1-30, P1-52 to 
55 


B, F1-24, Fi1-55 to 58 
B. ri-33 
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De, F1-36 
keep or discard prompt, 
G3-242.3 
l, F1-10 
a, B6-9, F1-39, F1-42 
av, G3-35 
2, F1-27, Fi-43, F1-45, 
F1-47 to 51 
v, see also format 


F1-25 
effect of DPP, G3-243 
monadic, D3-1 to 3, 
F1-25 
2, F1-22 


Comprehensive Index 
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